Abra API Overview

The Abra API lets you manage a store's Abra promotions, discounts, unique discount codes and webhook subscriptions from your own code. It's a REST API that takes and returns JSON. This page covers what every endpoint has in common. To make your first call, see Getting Started with the Abra API.

Base URL

Send requests to https://abra-api-333886610689.us-central1.run.app. The examples in this reference call it $ABRA_API_BASE and your token $ABRA_API_TOKEN.

Every call acts on the live store; there is no sandbox. Try your integration on a development store first. Browsers block calls to the API from other websites, so call it from your server, or test with curl or Postman.

https://abra-api-333886610689.us-central1.run.app

Authentication

Send the store's API token in the Authorization header of every request:

• Authorization: Bearer <token>

Generate the token in the Abra app under Settings > API access. It's shown only once, so copy it straight away. A token belongs to one store and can use every endpoint for that store; there are no scopes. If you work with several stores, you need one token per store.

Each store has one active token. It's valid for 365 days. Regenerating it, or revoking it in the same place, stops the old token working at once. A missing, expired or revoked token gets 401 with the code UNAUTHORIZED.

The examples on these pages use two shell variables. Set them once:

export ABRA_API_BASE="https://abra-api-333886610689.us-central1.run.app"
export ABRA_API_TOKEN="your-api-token"

To check that your token works, list your promotions:

curl "$ABRA_API_BASE/v1/partner/promotions" \
  -H "Authorization: Bearer $ABRA_API_TOKEN"

Rate limits

Each store can make 500 reads (GET) and 400 writes (POST, PUT, DELETE) in any 60 seconds. Reads and writes are counted separately. Responses include these headers:

• X-RateLimit-Limit: the limit for this kind of request.

• X-RateLimit-Remaining: requests left in the current window.

• X-RateLimit-Reset: Unix time, in seconds, by which the window has fully cleared.

Past the limit, you get 429 with the code RATE_LIMIT_EXCEEDED and a Retry-After header in seconds. Wait that long before you retry: requests that get a 429 still count toward the window.

Errors

Errors use standard HTTP status codes and one JSON shape: an error object with a machine-readable code and a description in words. When the request fails validation, the code is VALIDATION_FAILED and issues.fieldErrors lists the messages for each field by path, such as discounts.0.shopifyDiscountId. issues.formErrors holds messages that aren't about one field.

The codes below can come from several endpoints. Each endpoint lists its own. Discount endpoints can also return 400 with a code for a rule of one discount type, such as TIERED_TIER_THRESHOLD_NOT_INCREASING; error.description says what to fix.

error

Common error codes:

Pagination

List promotions and List discounts return one page at a time. Pass page (from 1) and limit (1 to 100, default 25). The items are in data, and pagination holds page, limit, total, totalPages, hasNextPage and hasPreviousPage. Ask for the next page while hasNextPage is true.

The other lists (webhook subscriptions and code generation jobs) come back in a single response.

Versioning

The version is part of the path. Every endpoint is under /v1, the only version today, so include it in every request. The API is in beta, so details can still change within /v1.

Endpoints

Promotions API

• List promotions: GET /v1/partner/promotions

• Create a promotion: POST /v1/partner/promotions

• Get a promotion: GET /v1/partner/promotions/{id}

• Update a promotion: PUT /v1/partner/promotions/{id}

• Delete a promotion: DELETE /v1/partner/promotions/{id}

• Deactivate a promotion: POST /v1/partner/promotions/{id}/deactivate

• Bulk update promotions: POST /v1/partner/promotions/bulk

Discounts API

• List discounts: GET /v1/partner/discounts

• Create a discount: POST /v1/partner/discounts

• Get a discount: GET /v1/partner/discounts/{id}

• Update a discount: PUT /v1/partner/discounts/{id}

• Delete a discount: DELETE /v1/partner/discounts/{id}

• Generate unique codes: POST /v1/partner/discounts/{id}/codes

• List code generation jobs: GET /v1/partner/discounts/{id}/codes/jobs

Webhooks API

• List webhook subscriptions: GET /v1/partner/webhooks

• Create a webhook subscription: POST /v1/partner/webhooks

• Get a webhook subscription: GET /v1/partner/webhooks/{id}

• Delete a webhook subscription: DELETE /v1/partner/webhooks/{id}

This page is generated from the Abra API specification (build bc96ccc) · ref b7f383905d1c. Edits made in Pylon are overwritten.