Skip to main content

​
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.
ParameterTypeDescription
grant_typestringauthorization_code, refresh_token, or client_credentials
client_idstringYour app’s client ID
client_secretstringYour app’s client secret
codestringAuthorization code (for authorization_code grant)
redirect_uristringMust match the URI used during authorization
code_verifierstringPKCE verifier (if code challenge was used)
refresh_tokenstringRefresh token (for refresh_token grant)
store_idstringTarget store (for client_credentials grant)
scopesstring[]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.
ParameterTypeRequiredDescription
tokenstringYesThe token to revoke
client_idstringYesYour app’s client ID
client_secretstringYesYour app’s client secret
token_type_hintstringNoaccess_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.
ParameterTypeRequiredDescription
session_tokenstringYesThe 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.

​
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

CodeDescription
400Bad request — check your request body or parameters
401Unauthorized — your token is invalid, expired, or revoked
403Forbidden — your token does not have the required scope
404Not found — the resource does not exist or is not accessible
429Too 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.