The API requires an access token for making authenticated requests. You can obtain an access token either by creating one manually in your supplier backoffice, or by following the OAuth authorization process when creating a public app.

1. Go to the API page in the Orderchamp back office to retrieve a private token
2. Enter this token in your header Authorization: Bearer {token}

If you are developing an app that multiple Orderchamp users can install, you will need to fetch a unique token for every user, which the user themselves needs to approve. This follows the general oAuth flow.

To get started with building a public app, you will also need to create a demo-account for Orderchamp Cloud. Please apply here .

Reach out to tech.support@orderchamp.com to create a partner account for you, and please mention the user-email that you used for setting up the demo-account, so we can attach it for you. You will receive a confirmation by e-mail, and you can login to your partner account by going to www.orderchamp.com/partners .

Within the partner account, you can create an app and retrieve the client_id and the client_secret which you need to construct the urls. You can set multiple urls, but two are required:

• Application url: To this url we'll send the user when they want to start the installation process. From here you redirect the user back to Orderchamp for the approval
• Redirect url: After the user has either approved or disapproved the installation of your app, we'll return the user to this url with a code (you can exchange the code for an access token)

You can also attach a logo, which will be visible in the integration overview.

(Tip: while in development its sometimes easier to start with a single token in your own demo-account as described in the Private app section, but you can also test-install the app on your own demo-account)

Once you're app is ready, you can send a message to our Tech Support team, and we'll verify that it works and the information is correct.

When you want to initiate the installation process for a user, simply redirect them to: https://www.orderchamp.com/oauth/authorize?response_type=code&client_id={CLIENT_ID}&scope={SCOPE}&redirect_uri={APP_URL}

• {CLIENT_ID}: Your App's CLIENT_ID
• {SCOPE}: Comma separated list of scopes, for example: scope=account_read,products_read
• {APP_URL}: Redirect URL used as callback to your app
• state: You can add your own custom variable to the url which we will return with the redirect url

When the user has either approved or disapproved the installation, we return them to your redirect_url but with the following parameters: https://example.org/auth/callback/uri?account_id={account_id}&code={authorization_code}&state={state}&timestamp=1570536833&signature=2ea417b02d293a55ea28d22f06658815e359061b054e641a5f627ee81012ea5a

• account_id: The unique orderchamp account id
• code: The code you can exchange for an access token (via the API)
• state: The state you sent us during the authorize url (if any)
• timestamp: Unix timestamp for verification
• signature: A signed HMAC to verify the request has not been tempered with

How to verify the signature:

• First remove the signature from the query string
• Push the remaining query string through a hmac function with sha256 and your client_secret

An example in PHP:

To exchange the code for a permanent access_token use the following API call

• {CODE}: The authorization code provided in the redirect
• {CLIENT_ID}: The API key for the app
• {CLIENT_SECRET}: The API secret key for the app

The API will respond with the access token and its approved scopes:

After the installation has finished, you can decide to leave the user in your application, or if you prefer to send the user back to their Orderchamp backoffice, simply redirect them to the following url: https://www.orderchamp.com/oauth/finish?client_id={your_app_client_id}

Part of the authorization process requires specifying which parts of an account's data the client would like access to. A client can ask for any of the authenticated or unauthenticated access scopes listed below.

• account_read, account_write: Access to Account
• products_read, products_write: Access to Product, Product Variant, Product Image
• orders_read, orders_write: Access to Orders, Order Product, Invoice, Invoice Item
• fulfillment_read, fulfillment_write: Create or update shipments
• customers_read, customers_write: Read or create customers