API Reference

Base URL

https://api.production.orderprotection.com

OAuth endpoints

These endpoints handle authentication and token management for your app.

Exchange tokens

POST /v1/oauth/token

Exchange an authorization code, refresh token, or client credentials for access tokens. See Authentication for detailed examples.

Parameter	Type	Description
`grant_type`	string	`authorization_code`, `refresh_token`, or `client_credentials`
`client_id`	string	Your app’s client ID
`client_secret`	string	Your app’s client secret
`code`	string	Authorization code (for `authorization_code` grant)
`redirect_uri`	string	Must match the URI used during authorization
`code_verifier`	string	PKCE verifier (if code challenge was used)
`refresh_token`	string	Refresh token (for `refresh_token` grant)
`store_id`	string	Target store (for `client_credentials` grant)
`scopes`	string[]	Scope filter (for `client_credentials` grant)

Response:

{
  "access_token": "op_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "op_rt_...",
  "scope": "read_orders read_claims"
}

Revoke a token

POST /v1/oauth/revoke

Revoke an access or refresh token.

Parameter	Type	Required	Description
`token`	string	Yes	The token to revoke
`client_id`	string	Yes	Your app’s client ID
`client_secret`	string	Yes	Your app’s client secret
`token_type_hint`	string	No	`access_token` or `refresh_token`

Response: 200 OK on success.

Verify session token

POST /v1/oauth/session/verify

Verify an embedded app session token and retrieve user context. See Embedded Apps for details.

Parameter	Type	Required	Description
`session_token`	string	Yes	The JWT session token from the iframe URL

Response:

{
  "userId": "user_abc123",
  "email": "merchant@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "storeId": "store_xyz789",
  "installationId": "inst_def456",
  "applicationId": "app_ghi012",
  "clientId": "op_app_...",
  "scopes": ["read_orders", "read_claims"]
}

This endpoint is rate-limited to 30 requests per minute per IP address.

Using access tokens

Once you have an access token, include it in the Authorization header of every API request:

curl -X GET https://api.production.orderprotection.com/v1/orders \
  -H "Authorization: Bearer op_at_af444635983c457a5e..."

Your access token is scoped to the store that installed your app and the permissions the merchant granted. You can use it to call any OrderProtection API endpoint that falls within your granted scopes.

Available APIs

With a valid access token, you can access these OrderProtection APIs:

Orders

Read and manage orders. Requires read_orders or write_orders scope.

Claims

Read and manage claims. Requires read_claims, write_claims, or manage_claims scope.

Products

Read and manage products. Requires read_products or write_products scope.

Fulfillments

Read and manage fulfillments. Requires read_orders scope.

Partner API (v2)

Manage settings, pricing rules, quotes, widgets, and A/B-test contexts via OAuth. Partner-only endpoints under /v2.

Error responses

When a request fails, the API returns a JSON error response:

{
  "statusCode": 403,
  "message": "Insufficient scope: read_analytics required",
  "error": "Forbidden"
}

Common error codes

Code	Description
`400`	Bad request — check your request body or parameters
`401`	Unauthorized — your token is invalid, expired, or revoked
`403`	Forbidden — your token does not have the required scope
`404`	Not found — the resource does not exist or is not accessible
`429`	Too many requests — you have exceeded the rate limit

If you receive a 401 response, try refreshing your access token. If that also fails, the merchant may have uninstalled your app.

Getting Started

Authentication

Analytics

Distribution

Reference

Base URL

OAuth endpoints

Exchange tokens

Revoke a token

Verify session token

Using access tokens

Available APIs

Orders

Claims

Products

Fulfillments

Partner API (v2)

Error responses

Common error codes

​Base URL

​OAuth endpoints

​Exchange tokens

​Revoke a token

​Verify session token

​Using access tokens

​Available APIs

Orders

Claims

Products

Fulfillments

Partner API (v2)

​Error responses

​Common error codes

Base URL

OAuth endpoints

Exchange tokens

Revoke a token

Verify session token

Using access tokens

Available APIs

Error responses

Common error codes