SellOrchard
Start free trial

API reference

Apps (OAuth)

Access tokens for App Store apps: exchange an authorization code, read the installation, uninstall.
On this page

Exchange an authorization code for an access token

post/oauth/token

Called by the app's backend with its client credentials (no bearer token). The code is single use and expires 10 minutes after the merchant approved; redirect_uri must be the one the code was issued for. Installs the app (or refreshes the token of an existing installation) and subscribes its webhook topics.

Request body

  • grant_typestring

    One of:authorization_code

  • client_idstringrequired
  • client_secretstringrequired
  • codestringrequired
  • redirect_uristringrequired

Example request

curl
curl -X POST "https://api.sellorchard.com/v1/oauth/token" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "app_k2m9x7q4w1e8r5t3y6u0i2o4",
  "client_secret": "so_secret_...",
  "code": "Xf8kQ2...",
  "redirect_uri": "https://myapp.example.com/sellorchard/callback"
}'

Response200The access token (store it securely; it is not shown again).

Show response schema
  • access_tokenstringrequired
  • token_typestring
  • scopestringrequired

    Granted scopes, space-separated.

  • installation_idinteger
  • storeobjectrequired
    Show child attributes
    • idstring
    • namestring
    • domainstring
200 response
{
  "access_token": "so_app_...",
  "token_type": "bearer",
  "scope": "read_products write_orders",
  "installation_id": 42,
  "store": {
    "id": "01JD4Z8T6Q2W9X5V3B7N1M0K8H",
    "name": "Orchard Goods",
    "domain": "orchard-goods.sellorchard.store"
  }
}

Error responses

  • 400invalid_requestMalformed request (e.g. a bad cursor).
  • 401authenticationMissing, invalid, expired or revoked API key.
  • 403permissionThe key lacks the scope, or the store's plan doesn't include the API.
  • 422invalid_requestInvalid parameters; errors lists each field.
  • 429rate_limitedToo many requests.
  • 500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

The access token's installation

get/oauth/installation

App access tokens only (an API key gets 403). The store, the granted scopes and when it was installed.

Example request

curl
curl "https://api.sellorchard.com/v1/oauth/installation" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY"

Response200The installation of the access token.

Show response schema
  • dataobjectrequired
    Show child attributes
    • objectstring
    • idinteger
    • statusstring

      One of:activeuninstalled

    • appobject
    • storeobject
    • scopesarray of string
    • installed_atstring<date-time>
    • uninstalled_atstring<date-time> | null
200 response
{
  "data": {
    "object": "app_installation",
    "id": 42,
    "status": "active",
    "app": {
      "client_id": "app_k2m9x7q4w1e8r5t3y6u0i2o4",
      "name": "Order Sync",
      "slug": "order-sync"
    },
    "store": {
      "id": "01JD4Z8T6Q2W9X5V3B7N1M0K8H",
      "name": "Orchard Goods",
      "domain": "orchard-goods.sellorchard.store"
    },
    "scopes": [
      "read_products",
      "write_orders"
    ],
    "installed_at": "2026-11-02T15:00:00Z",
    "uninstalled_at": null
  }
}

Error responses

  • 401authenticationMissing, invalid, expired or revoked API key.
  • 403permissionThe key lacks the scope, or the store's plan doesn't include the API.
  • 429rate_limitedToo many requests.
  • 500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Uninstall the app

delete/oauth/installation

The app removes itself from the store: the token stops working at once, its webhook subscriptions are removed and app.uninstalled is sent (uninstalled_by "app").

Example request

curl
curl -X DELETE "https://api.sellorchard.com/v1/oauth/installation" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY"

Response200The installation of the access token.

Show response schema
  • dataobjectrequired
    Show child attributes
    • objectstring
    • idinteger
    • statusstring

      One of:activeuninstalled

    • appobject
    • storeobject
    • scopesarray of string
    • installed_atstring<date-time>
    • uninstalled_atstring<date-time> | null
200 response
{
  "data": {
    "object": "app_installation",
    "id": 42,
    "status": "active",
    "app": {
      "client_id": "app_k2m9x7q4w1e8r5t3y6u0i2o4",
      "name": "Order Sync",
      "slug": "order-sync"
    },
    "store": {
      "id": "01JD4Z8T6Q2W9X5V3B7N1M0K8H",
      "name": "Orchard Goods",
      "domain": "orchard-goods.sellorchard.store"
    },
    "scopes": [
      "read_products",
      "write_orders"
    ],
    "installed_at": "2026-11-02T15:00:00Z",
    "uninstalled_at": null
  }
}

Error responses

  • 401authenticationMissing, invalid, expired or revoked API key.
  • 403permissionThe key lacks the scope, or the store's plan doesn't include the API.
  • 429rate_limitedToo many requests.
  • 500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.