Public API Access

BackstockOps includes a public API for approved external systems, such as a reporting tool, warehouse workflow, or internal integration.

Public API access is available on the Scale plan. Stores on lower plans will not be able to create or use public API keys.

The public API is GraphQL-only. Use:

POST /api/public/graphql

Older REST-style public API URLs do not return store data. They return a GraphQL-only response that points integrations to /api/public/graphql.

Before You Start

You need:

• A BackstockOps store on the Scale plan
• Permission to manage API keys in BackstockOps
• An external system that can send HTTPS requests with a bearer token

Public API keys should be treated like passwords. Store them securely and revoke any key that is no longer needed.

Create An API Key

1. Open BackstockOps from Shopify Admin.
2. Go to Settings.
3. Open the API access area.
4. Enter a key name that identifies the integration.
5. Choose the scopes the integration needs.
6. Create the key.
7. Copy the secret immediately.

The secret is only shown once. If it is lost, rotate the key or create a new one.

Available Scopes

Use the smallest set of scopes the integration needs.

• read_status: store/API key status
• read_suppliers: supplier records
• read_purchase_orders: purchase order summaries
• read_replenishment: replenishment recommendations and related items

If a GraphQL query asks for data outside the key's scopes, BackstockOps returns a scope error for that field.

Send A Request

Send the API key as a bearer token in the Authorization header.

curl -X POST "https://app.backstockops.com/api/public/graphql" \
  -H "Authorization: Bearer bso_pk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ status { shop apiKey { name prefix scopes active lastUsedAt } } }"}'

Example Queries

Check API status:

query PublicApiStatus {
  status {
    shop
    apiKey {
      name
      prefix
      scopes
      active
      createdAt
      lastUsedAt
    }
  }
}

List suppliers:

query Suppliers {
  suppliers(limit: 50) {
    id
    name
    companyName
    contactName
    email
    currency
    paymentTerms
    defaultLeadTimeDays
    restockPeriodDays
    updatedAt
  }
}

List purchase orders:

query PurchaseOrders {
  purchaseOrders(limit: 50) {
    id
    poNumber
    status
    archived
    currency
    subtotal
    totalCost
    lineCount
    expectedAt
    sentAt
    receivedAt
    updatedAt
    supplier {
      id
      name
    }
    destinationLocation {
      id
      name
    }
  }
}

List replenishment recommendations:

query ReplenishmentRecommendations {
  replenishmentRecommendations(limit: 50) {
    id
    urgencyScore
    daysUntilStockout
    reorderPoint
    suggestedQuantity
    averageDailySales
    generatedAt
    variant {
      id
      shopifyVariantGid
      sku
      productTitle
      variantTitle
    }
    location {
      id
      name
    }
  }
}

Rate Limits

BackstockOps uses a point-based rate limit to protect stores from runaway integrations.

Each API key has a rate-limit bucket:

• Bucket size: 1,000 points
• Restore rate: 20 points per second
• Simple status queries cost 1 point
• List queries cost more based on the requested limit
• Querying multiple top-level fields in one request adds their costs together

This means a small status check can run frequently, while large repeated list queries are slowed down before they can overload the store.

Every successful GraphQL response includes rate-limit headers:

• X-BackstockOps-RateLimit-Limit: maximum points available in the bucket
• X-BackstockOps-RateLimit-Remaining: points left after the request
• X-BackstockOps-RateLimit-Cost: points consumed by the request
• X-BackstockOps-RateLimit-Reset: estimated time when the bucket is full again

If the integration exceeds the limit, BackstockOps returns 429 and includes Retry-After.

When you receive 429, wait at least the number of seconds in Retry-After before sending another request.

Common Responses

• 200: request was accepted. GraphQL field errors may still appear in the response body.
• 400: the GraphQL query was missing or malformed.
• 401: the bearer token is missing, invalid, rotated, or revoked.
• 403: the key does not have the required scope or API access is unavailable.
• 410: the REST-style public API route is no longer used. Use GraphQL.
• 429: the integration exceeded the API rate limit.

Rotate Or Revoke A Key

Rotate a key when the secret may have been exposed or when an integration needs a fresh secret.

Revoking a key immediately stops that key from working. BackstockOps will return 401 for requests using a revoked key.

Troubleshooting

If an integration cannot connect:

1. Confirm the store is on the Scale plan.
2. Confirm public API access is enabled in BackstockOps settings.
3. Confirm the request uses POST /api/public/graphql.
4. Confirm the Authorization header uses Bearer followed by the API key.
5. Confirm the key has the scope required by the query.
6. Check for 429 responses and follow the Retry-After header.
7. Rotate the key if the secret may be incorrect or stale.

If the integration is still blocked, contact support with the response status, timestamp, and the API key prefix. Do not send the full API key secret.