Start connecting Shopify
const url = 'https://api.elephants.inc/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/integrations/shopify/authorize-url';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"return_path":"example","shop":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.elephants.inc/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/integrations/shopify/authorize-url \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "return_path": "example", "shop": "example" }'Mints the URL to send the user to in order to connect a Shopify store.
Same handshake as the Xero equivalent, and the same return_path rules.
shop is required because Shopify’s consent screen is per-store. It is
normalised first, so my-store, My-Store.myshopify.com and
https://my-store.myshopify.com all resolve to the same store. A URL
carrying a path — the admin URL, say — does not: normalisation strips the
scheme but not the path, so that is a 422, as is anything else that is not
a valid myshopify.com store.
The user can still change store on Shopify’s own screen. The connection
that lands is whichever store Shopify signs in its callback, which may not
be the one asked for here — read GET /integrations for the truth rather
than assuming.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Organization the connection will belong to
Request Bodyrequired
Section titled “Request Bodyrequired”Store to connect, and where to return the user
object
Same-origin path to return the user to once the handshake finishes. Must start with a single /; anything that could name a host is rejected.
The store’s myshopify.com domain. A bare handle (my-store) or the full domain works, with or without a scheme; a URL carrying a path does not.
Example generated
{ "return_path": "example", "shop": "example"}Responses
Section titled “Responses”Where to send the user
object
After this the URL’s state is stale and the handshake will be refused.
Send the user here. Connecting completes on the redirect back.
Example generated
{ "expires_at": "2026-04-15T12:00:00Z", "url": "example"}Invalid request parameters or body
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Too many requests
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
object
Example
{ "error": { "type": "rate_limited" }}Headers
Section titled “Headers”How long to wait before retrying, expressed as delay seconds or an HTTP date
Unexpected server error
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}