Ordexs API v1 Get an API key

Get started

Connect apps with OAuth

Build an app any Ordexs merchant can connect with one approval, instead of copying an API key. Authorization code with PKCE, one-hour access tokens and rotating refresh tokens.

An API key is the right tool when a merchant connects their own systems. If you build an app that many merchants use, ask them to approve it instead: they click your link, pick a store, see exactly what your app may do, and press Approve. You never handle a key they had to copy by hand, and they can disconnect you at any time.

There is no app directory and no review. Any Ordexs account can register an app; it is reached only through the approval link you send.

Register your app

In the dashboard, open Settings → Developers → Your apps and press New app. You give:

  • App name: merchants see it on the approval screen.
  • Website (optional, https://).
  • Redirect URLs: one to five. Merchants return to one of these after approving. They must be https://, or http://localhost / http://127.0.0.1 while you develop. The redirect_uri you send must match one of them exactly.
  • Permissions: the scopes your app may ask for. A request can ask for some or all of them, never others.

You get a client ID (app_…) and a client secret (ordx_cs_…). The secret is shown once; keep it on your server. If it leaks, make a new one from the same menu: the old secret stops working at once.

Apps belong to your account, not to a store, and you can have up to 10.

1. Send the merchant to the approval screen

Create a PKCE pair: a random code_verifier (43 to 128 characters) and its code_challenge, the base64url SHA-256 of the verifier. Keep the verifier for step 3. Then send the merchant to:

GET https://admin.ordexs.com/oauth/authorize
  ?response_type=code
  &client_id=app_9fK2mQ7xL4pR8tW1vY6zB3nC
  &redirect_uri=https://app.example.com/ordexs/callback
  &scope=store:read orders:read orders:write
  &state=Hk29xLq0
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
Parameter
response_typeAlways code.
client_idYour app's client ID.
redirect_uriOne of your registered redirect URLs, exactly.
scopeSpace-separated scopes, from the ones your app registered.
stateA random value you check when the merchant comes back. Recommended.
code_challengeThe PKCE challenge. Required.
code_challenge_methodAlways S256.
modelive (default) or test. A test connection works on the store's test data.

The merchant signs in if needed, picks one of the stores they own or administer (on a plan that includes the API) and approves. Only the store owner and admins can approve apps.

2. The merchant comes back

On approval, Ordexs redirects to your redirect_uri with a code:

https://app.example.com/ordexs/callback?code=…&state=Hk29xLq0

Check that state is the value you sent. The code is valid for 10 minutes and works once.

If the merchant presses Deny, you get error=access_denied. If you asked for a scope your app didn't register, you get error=invalid_scope. A wrong client_id or redirect_uri never redirects: the merchant sees an error on Ordexs instead.

3. Exchange the code for tokens

From your server, with your client secret (in the body, or as HTTP Basic auth):

curl https://api.ordexs.com/oauth/token \
  -d grant_type=authorization_code \
  -d code=… \
  -d redirect_uri=https://app.example.com/ordexs/callback \
  -d code_verifier=… \
  -u app_9fK2mQ7xL4pR8tW1vY6zB3nC:ordx_cs_…
{
  "access_token": "ordx_live_Ab3dEf6hIj9k_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ordx_rt_…",
  "scope": "store:read orders:read orders:write",
  "store_id": "sto_52cac290122d48909…",
  "livemode": true
}

The access token is used exactly like an API key (see Authentication): same header, same scopes, same rate limits. store_id is the store the merchant picked (its test store for a test connection). It lasts one hour. After that, requests answer 401 invalid_api_key with a message telling you to refresh.

Approving your app again for the same store and mode replaces the earlier connection. Using a code twice is treated as theft: the connection is cut and every token from it stops working.

4. Refresh

curl https://api.ordexs.com/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=ordx_rt_… \
  -u app_9fK2mQ7xL4pR8tW1vY6zB3nC:ordx_cs_…

You get a new access token and a new refresh token; the old refresh token and the old access token stop working. Refresh tokens last 60 days from when they were issued, so an app that refreshes at least every two months stays connected. The scopes stay the ones the merchant approved.

Webhooks for your app

With the webhooks:write scope, register your endpoints with POST /v1/webhook_endpoints right after the merchant approves. An endpoint created with an OAuth token belongs to that connection:

  • your app lists and changes only its own endpoints, never the merchant's;
  • it is deleted when the merchant disconnects your app, when they approve it again (the new connection starts clean), or when you delete the app.

So register them again after every approval. When the order of events matters to you, re-read the object by id (see Webhooks).

What a typical app uses

An app that sells for the merchant (a chat or voice agent, a marketplace connector) usually needs these. The scope each one needs is in brackets.

NeedHow
Store name, currency and its decimalsGET /v1/store (store:read)
The catalogue, then only what changedGET /v1/products?status=published, then ?updated_since=; a variant's stock or price change counts (products:read)
One product from a SKU or a pasted linkGET /v1/products?sku= or ?handle=; a published product carries its url
Where the store delivers, and for how muchGET /v1/regions, GET /v1/delivery/rates?region= (no scope)
The exact total, before the customer confirmsPOST /v1/orders/preview (orders:write)
Place the order, never twicePOST /v1/orders with external_id and source_name; a repeat answers 409 duplicate_external_id with the existing order in details.order
"Where is my order?"GET /v1/orders?phone= or ?external_id=, then GET /v1/orders/{order_id}/tracking (orders:read)
Cancel at the customer's requestPOST /v1/orders/{order_id}/cancel (orders:write); the stock goes back
Hear about changesorder.updated, order.status_changed, product.updated, inventory.updated, product.deleted (webhooks:write)

Prices are always the store's. You send what was ordered, never a price, and every amount comes back as a decimal string in the store's currency.

Disconnecting

  • You: POST https://api.ordexs.com/oauth/revoke with token= (an access or refresh token) and your client credentials. It always answers 200, as RFC 7009 asks.
  • The merchant: Settings → Developers → Connected apps → Disconnect. Tokens stop working within 30 seconds; your next refresh answers invalid_grant.
  • Deleting your app disconnects every store that approved it.

Errors from the token endpoint

The token endpoint answers in the OAuth format, not the API error format:

{ "error": "invalid_grant", "error_description": "This authorization code expired (codes last 10 minutes). Ask the merchant to approve again." }
errorStatusMeaning
invalid_request400A required field is missing.
invalid_client401The client ID and secret don't match an app.
invalid_grant400The code or refresh token is wrong, expired, already used, or the connection was cut.
unsupported_grant_type400Only authorization_code and refresh_token are supported.

Plans

Connections use the store's API access, so the store must be on Starter, Growth or Scale. OAuth tokens don't count toward the plan's API key limit. If the store moves to Try, requests answer 402 plan_required until it upgrades.