All requests must use HTTPS.
Add an Idempotency-Key header to write operations to avoid duplicates.
Detailed specs live under Resources below.

​
Base URLs

Sandbox    https://sandbox.api.withgale.com/v1
Production will-be-shared-once-integration-is-complete

​
Authentication

Every request needs an Authorization header:

Authorization: Bearer <YOUR_MERCHANT_API_TOKEN>

  1. In the Gale Dashboard open Settings → API Keys.

  2. Copy your merchant_api_token.

  3. Send it on every call, e.g.

    Authorization: Bearer <merchant_api_token>

Missing or invalid tokens return:

HTTP/1.1 401 Unauthorized

​
Rate Limits

  • 100 requests / minute / merchant (burst to 200).

  • Exceeding the limit yields:

    HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>

    Wait the indicated seconds, then retry.

​
Idempotency

Add an Idempotency-Key header to every state-changing POST:

Idempotency-Key: <uuid-v4-string>

Re-using the same key within 24 h returns the original response (no duplicates).
GET and DELETE calls ignore this header.

​
Error Envelope

{
  "success": false,
  "error_code": 422,
  "error_type": "unprocessable_entity",
  "error_message": "Validation failed: product_internal_id is required.",
  "details": {
    "field_errors": {
      "product_internal_id": ["product_internal_id is required"]
    }
  }
}
HTTP StatusMeaningTypical Cause
400 Bad RequestMalformed JSON / missing fieldsBody isn’t valid JSON or a required attribute is absent
401 UnauthorizedMissing / invalid tokenAuthorization header absent, expired, or malformed
403 ForbiddenNot permittedToken valid but merchant doesn’t own the resource
404 Not FoundResource absentproduct_id, checkout_id, etc. does not exist
409 ConflictInvalid state changee.g. cancelling a checkout already PAID
422 Unprocessable EntityValidation failedField has wrong type / value
429 Too Many RequestsRate-limit hitToo many calls in a short burst
500 Internal Server ErrorUnexpected server issueSomething went wrong on Gale’s side – retry after a few minutes

​
Resources

Products

Create, list, update, delete, and check HSA/FSA eligibility for every item.

Checkout

Create hosted checkouts, fetch status, refund, or cancel a session.

Webhooks

Receive real-time events for checkout status and product-eligibility changes.

Subscription Plans

Create recurring-billing plans and attach one or many to your products.

Next step: choose a resource above to dive into its endpoints.