API Reference

Base URL

https://api.production.orderprotection.com

OAuth endpoints

These endpoints handle authentication and token management for your app.

POST /v1/auth/login

Authenticates a dashboard user ({"email", "password"}) and returns {"data": {"access_token", "refresh_token", "expires_in", ...}}. The access_token is the dashboard user JWT required by the install endpoints below — app access tokens and personal access tokens are rejected there. Refresh with POST /v1/auth/refresh {"refreshToken"}. See Installing Your App.

Install an app (authorize/approve)

POST /v1/oauth/authorize/approve

Creates an installation on a store and returns a single-use authorization code. Requires a dashboard user JWT for a user with access to the store.

Parameter	Type	Description
`clientId`	string	Your app’s client ID
`redirectUri`	string	Must exactly match a registered redirect URI
`scopes`	string[]	Must include every required scope; must not exceed the app’s declared scopes
`storeId`	string	Target store
`state`	string	Optional; echoed into the returned redirect URL
`codeChallenge` / `codeChallengeMethod`	string	Optional PKCE (S256 only)

Response: {"data": {"code": "...", "redirectUri": "https://...?code=..."}}. Full walkthrough and error table: Installing Your App. To preview an app’s consent payload first: POST /v1/oauth/authorize with {"clientId", "redirectUri"} (same auth).

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": "order:read claim:read"
}

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": ["order:read", "claim:read"]
}

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 order:read or order:update scope.

Claims

Read and manage claims. Requires claim:read, claim:update, or claim:manage scope.

Products

Read and manage products. Requires product:read or product:update scope.

Fulfillments

Read and manage fulfillments. Requires order:read 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

Install an app (authorize/approve)

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

​User login

​Install an app (authorize/approve)

​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

User login

Install an app (authorize/approve)

Exchange tokens

Revoke a token

Verify session token

Using access tokens

Available APIs

Error responses

Common error codes