Skip to main content

API Integrations

An API integration is an app that runs on your own server and works with the merchant's data through the SitePack REST API: syncing products and stock with an ERP, sending orders to a warehouse, pushing leads into a CRM, connecting a POS.

To do that, your app needs the merchant's permission. SitePack uses OAuth 2.0 for this: the merchant approves your app on a consent screen, and your server receives an access token for their site, limited to the scopes they granted.

Do you need OAuth?​

You want to...OAuth?
Show a button, banner, popup or widget on the storefrontNo
Load a tag manager, pixel or analytics scriptNo
React to cart and checkout events in the browserNo
Let the merchant configure your appNo, use App Settings
Read or change orders, products, stock, customers or contentYes
Receive webhooks on your serverYes
Read the merchant's settings from your own serverYes (app:settings:read)

If everything you need is in the first four rows, build a storefront app instead. It installs with one click from the Marketplace and you have nothing to host.

How it fits together​

  1. The merchant clicks Install in the Marketplace, or your own Connect SitePack button that opens your install link.
  2. SitePack shows the consent screen: your app, the site it is installed on (the merchant's current site), the permissions you ask for in plain language and, for a paid app, the price.
  3. The merchant approves. SitePack installs the app on that site and sends the merchant to your redirect URI with a one-time code.
  4. Your server exchanges the code for an access token and a refresh token, and stores them for that site.
  5. Your server calls the API with the token and receives webhooks for the events you subscribed to.
  6. When your own onboarding is done, you send the merchant back to SitePack.

Step by step​

Step 1: Declare the scopes​

List every scope your app uses under auth.scopes in app.json. Ask only for what you use: the merchant sees every scope on the consent screen, and unused scopes are a reason to reject an app in review.

{
  "auth": {
    "scopes": ["products:read", "inventory:write", "orders:read", "app:settings:read"]
  }
}

Publish with sitepack app:publish.

Step 2: Enable OAuth in the Partner Portal​

Open your app in the Partner Portal and go to the OAuth & install card:

  1. Click Enable OAuth.
  2. Enter your Redirect URI, for example https://your-app.com/sitepack/callback, and save it.
  3. Store the Client ID, Client secret and Webhook signing secret on your server, for example as environment variables. Never put them in browser code or in your app's files.

The card now also shows your Install link. See the Partner Portal guide.

Step 3: Handle the callback​

After approval, SitePack redirects the merchant to your redirect URI:

https://your-app.com/sitepack/callback?code=...&state=...&signed_at=...&signature=v1=...&manage_url=...

On your server:

  1. Check that state matches the value you put in the install link.
  2. Verify signature with your webhook signing secret (recommended).
  3. Exchange code for tokens.
  4. Store the tokens with the site they belong to.

The exact requests are in Authentication (OAuth).

Step 4: Call the API​

All requests go to https://api.sitepack.eu. Send the access token on every request:

GET https://api.sitepack.eu/api/public/v1/orders
X-SitePack-Access-Token: YOUR_ACCESS_TOKEN

Every endpoint is listed on API Endpoints, with the scope it needs. The API Reference has the parameters and example responses.

Refresh the token before it expires. A 401 means the token expired or the merchant removed your app; a 403 means the call needs a scope you do not have.

Step 5: Subscribe to webhooks​

Add the topics you want to your app.json and publish. SitePack posts a small, signed message to your server when something happens; you read the details back through the API. See Webhooks.

Step 6: Send the merchant back​

The callback includes manage_url, the page in the merchant's SitePack admin where your app lives. When your own onboarding is finished, redirect the merchant there. With App Settings, that page already holds your settings form, so the merchant finishes setting up your app inside SitePack.

Combine it with SitePack settings​

An API integration is still configured best with a SitePack settings form. Put things like a warehouse code or a "send orders" switch in admin.settings_schema and read them on your server with GET /api/public/v1/app/settings. You do not build or host a settings screen, and the merchant never has to sign in to your service to change a setting.

Next steps​