SellApp
API ReferenceExports

Exports

Create and download sales, tax, customer, and affiliate payout reports.

Create a report without keeping your request open. Each export has its own UUID and saved progress, so you can check it later. Exports cover several kinds of store data and are available at /v2/exports independently of any one order.

Reports contain real store data. Keep downloaded files private. SellApp records who requested an export; the response does not expose that person's identifier.

Permissions by report type

Send X-STORE with your store slug. You need an API key with the listed ability for an ordinary SDK/REST integration. Official CLI and MCP connections use the admin grant; the table names their reviewed operation permissions, not scopes to request during login. Your current store permissions remain required.

typeAPI-key abilityReviewed create permissionReviewed read permissionStore permissions
sales, tax, customersinvoiceorders:writeorders:readinvoice
affiliate_payoutsaffiliatepayments:writepayments:readBoth affiliate and affiliate:payout

The list returns only report types you may access, 50 reports per page. Retrieving or downloading another store's export returns 404; lacking access to its report category returns 403. Affiliate payout reports describe commissions and merchant-recorded payments, not transfers made by SellApp.

Create, check, and download

Use csv or json for any supported type. Optional parameters.from and parameters.to use YYYY-MM-DD. Both dates are inclusive. Omitted or null to uses today; omitted or null from uses 365 days before to. The resulting range may span at most 366 calendar days. Sales and tax use sale update dates; customers and affiliate payouts use creation dates. Tax reports accept parameters.report_type as summary or detailed.

Only one export per store and two per requesting account may be queued or running, across credentials and stores. Capacity failures return 429 with Retry-After: 60; wait and poll an existing export. Jobs may wait up to 15 minutes to start and run for at most 300 seconds, including up to 240 seconds of report generation.

Reports are limited to 100,000 source rows, 50 MiB of serialized source data, and a 100 MiB output file. Tax summaries count the underlying sales rows. Exceeding a limit fails the job without publishing a partial file. Request a smaller date range after inspecting failure_message.

Set the environment variables from the quickstart. These Bash commands require jq and create a real export. Save one EXPORT_REQUEST_KEY for this request; reuse it only for an identical retry.

Create a sales export
EXPORT_REQUEST_KEY="$(openssl rand -hex 16)"
EXPORT_RESPONSE="$(curl --fail-with-body --request POST \
  --url "${SELLAPP_API_BASE_URL}/v2/exports" \
  --header "Authorization: Bearer ${SELLAPP_API_KEY}" \
  --header "X-STORE: ${SELLAPP_STORE_SLUG}" \
  --header "Idempotency-Key: ${EXPORT_REQUEST_KEY}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"type":"sales","format":"csv","parameters":{"from":"2026-08-01","to":"2026-08-31"}}')"
EXPORT_ID="$(printf '%s' "$EXPORT_RESPONSE" | jq -er '.data.id')"

The response includes meta.poll_after_seconds: 2. Wait at least that long, then retrieve the returned ID. Repeat this read while status is pending or running; do not create a new export on every poll.

Check the export
EXPORT_RESPONSE="$(curl --fail-with-body \
  --url "${SELLAPP_API_BASE_URL}/v2/exports/${EXPORT_ID}" \
  --header "Authorization: Bearer ${SELLAPP_API_KEY}" \
  --header "X-STORE: ${SELLAPP_STORE_SLUG}" \
  --header 'Accept: application/json')"
printf '%s' "$EXPORT_RESPONSE" | jq '.data | {id, status, filename, size, expires_at}'

The resource includes type, format, parameters, status, filename, content_type, byte size, and failure_message. Timestamps describe creation, updates, the start of generation, completion, failure, and expiration. Artifact metadata and lifecycle timestamps can be null before the corresponding step.

When status is completed and expires_at is in the future, use the returned download_url. It is a signed SellApp API URL valid for five minutes. Request it with your credential and X-STORE; it redirects to a separate private storage URL valid for five minutes. Send your API credential only to SellApp, not to the storage URL. Do not log either signed URL. Retrieve the export again if the SellApp download link expires while the artifact is still available.

Failures and expiration

A download attempted before completion returns 409. An expired artifact returns 410, even if its last reported status still says completed. Expired artifacts have no download_url. Expiration cleanup may finish later; that does not extend download access.

Generation is attempted once. If status becomes failed, inspect the public failure_message, then create a new export with a new request key when ready. Retrying the original keyed create request retrieves the original result; it does not restart failed generation. A missing artifact can return 404.

POST
/v2/exports

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Header Parameters

Idempotency-Key?string

Reuse this key only for an identical retry. A replay returns Idempotent-Replayed: true.

Length8 <= length <= 255
X-STORE?string

Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://sell.app/api/v2/exports" \  -H "Idempotency-Key: project-library-2026-09-04" \  -H "X-STORE: launch-lab" \  -H "Content-Type: application/json" \  -d '{    "type": "sales",    "format": "csv",    "parameters": {      "from": "2026-08-01",      "to": "2026-08-31"    }  }'
{
  "data": {
    "id": "01992a65-e064-71ba-b38f-902b7966a6be",
    "type": "sales",
    "format": "csv",
    "status": "pending",
    "parameters": {
      "from": "2026-08-01",
      "to": "2026-08-31"
    },
    "filename": null,
    "content_type": null,
    "size": null,
    "failure_message": null,
    "started_at": null,
    "completed_at": null,
    "failed_at": null,
    "expires_at": null,
    "created_at": "2026-09-04T09:12:00Z",
    "updated_at": "2026-09-04T09:12:03Z"
  },
  "meta": {
    "poll_after_seconds": 2
  }
}
{
  "type": "invalid_request_error",
  "code": "bad_request",
  "message": "The request could not be understood.",
  "status": 400,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#bad-request"
}
{
  "type": "authentication_error",
  "code": "unauthenticated",
  "message": "Unauthenticated.",
  "status": 401,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}
{
  "type": "authorization_error",
  "code": "forbidden",
  "message": "This action is unauthorized.",
  "status": 403,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#forbidden"
}
{
  "type": "not_found_error",
  "code": "resource_not_found",
  "message": "Not Found.",
  "status": 404,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#resource-not-found"
}
{
  "type": "conflict_error",
  "code": "conflict",
  "message": "The resource state changed before this request.",
  "status": 409,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#conflict"
}
{
  "type": "invalid_request_error",
  "code": "cursor_expired",
  "message": "This cursor has expired. Start again without a cursor.",
  "status": 410,
  "param": "cursor",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#cursor-expired"
}
{
  "type": "validation_error",
  "code": "validation_failed",
  "message": "The selected product variant id is invalid.",
  "status": 422,
  "param": "product_variant_id",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#validation-failed",
  "errors": {
    "product_variant_id": [
      "The selected product variant id is invalid."
    ]
  }
}
{
  "type": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too Many Attempts.",
  "status": 429,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}
{
  "type": "api_error",
  "code": "api_error",
  "message": "Server Error",
  "status": 500,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#api-error"
}
GET
/v2/exports

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Header Parameters

X-STORE?string

Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://sell.app/api/v2/exports" \  -H "X-STORE: launch-lab"
{
  "data": [
    {
      "id": "01992a65-e064-71ba-b38f-902b7966a6be",
      "type": "sales",
      "format": "csv",
      "status": "completed",
      "parameters": {
        "from": "2026-08-01",
        "to": "2026-08-31"
      },
      "download_url": "https://sell.app/api/v2/exports/01992a65-e064-71ba-b38f-902b7966a6be/download?expires=1788513423&signature=2c91df645a086ec399153a932b741f809d2b85c69740eaf3612384ebfb913a65",
      "filename": "sales-2026-08-01-to-2026-08-31.csv",
      "content_type": "text/csv",
      "size": 18432,
      "failure_message": null,
      "started_at": "2026-09-04T09:12:01Z",
      "completed_at": "2026-09-04T09:12:03Z",
      "failed_at": null,
      "expires_at": "2026-09-05T09:12:03Z",
      "created_at": "2026-09-04T09:12:00Z",
      "updated_at": "2026-09-04T09:12:03Z"
    }
  ],
  "links": {
    "first": "https://sell.app/api/v2/exports?page=1",
    "last": "https://sell.app/api/v2/exports?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://sell.app/api/v2/exports",
    "per_page": 50,
    "to": 1,
    "total": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://sell.app/api/v2/exports?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ]
  }
}
{
  "type": "invalid_request_error",
  "code": "bad_request",
  "message": "The request could not be understood.",
  "status": 400,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#bad-request"
}
{
  "type": "authentication_error",
  "code": "unauthenticated",
  "message": "Unauthenticated.",
  "status": 401,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}
{
  "type": "authorization_error",
  "code": "forbidden",
  "message": "This action is unauthorized.",
  "status": 403,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#forbidden"
}
{
  "type": "not_found_error",
  "code": "resource_not_found",
  "message": "Not Found.",
  "status": 404,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#resource-not-found"
}
{
  "type": "conflict_error",
  "code": "conflict",
  "message": "The resource state changed before this request.",
  "status": 409,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#conflict"
}
{
  "type": "invalid_request_error",
  "code": "cursor_expired",
  "message": "This cursor has expired. Start again without a cursor.",
  "status": 410,
  "param": "cursor",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#cursor-expired"
}
{
  "type": "validation_error",
  "code": "validation_failed",
  "message": "The selected product variant id is invalid.",
  "status": 422,
  "param": "product_variant_id",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#validation-failed",
  "errors": {
    "product_variant_id": [
      "The selected product variant id is invalid."
    ]
  }
}
{
  "type": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too Many Attempts.",
  "status": 429,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}
{
  "type": "api_error",
  "code": "api_error",
  "message": "Server Error",
  "status": 500,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#api-error"
}
GET
/v2/exports/{export}

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Path Parameters

export*string

The export identifier.

Formatuuid

Header Parameters

X-STORE?string

Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://sell.app/api/v2/exports/01992a65-e064-71ba-b38f-902b7966a6be" \  -H "X-STORE: launch-lab"
{
  "data": {
    "id": "01992a65-e064-71ba-b38f-902b7966a6be",
    "type": "sales",
    "format": "csv",
    "status": "completed",
    "parameters": {
      "from": "2026-08-01",
      "to": "2026-08-31"
    },
    "download_url": "https://sell.app/api/v2/exports/01992a65-e064-71ba-b38f-902b7966a6be/download?expires=1788513423&signature=2c91df645a086ec399153a932b741f809d2b85c69740eaf3612384ebfb913a65",
    "filename": "sales-2026-08-01-to-2026-08-31.csv",
    "content_type": "text/csv",
    "size": 18432,
    "failure_message": null,
    "started_at": "2026-09-04T09:12:01Z",
    "completed_at": "2026-09-04T09:12:03Z",
    "failed_at": null,
    "expires_at": "2026-09-05T09:12:03Z",
    "created_at": "2026-09-04T09:12:00Z",
    "updated_at": "2026-09-04T09:12:03Z"
  }
}
{
  "type": "invalid_request_error",
  "code": "bad_request",
  "message": "The request could not be understood.",
  "status": 400,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#bad-request"
}
{
  "type": "authentication_error",
  "code": "unauthenticated",
  "message": "Unauthenticated.",
  "status": 401,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}
{
  "type": "authorization_error",
  "code": "forbidden",
  "message": "This action is unauthorized.",
  "status": 403,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#forbidden"
}
{
  "type": "not_found_error",
  "code": "resource_not_found",
  "message": "Not Found.",
  "status": 404,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#resource-not-found"
}
{
  "type": "conflict_error",
  "code": "conflict",
  "message": "The resource state changed before this request.",
  "status": 409,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#conflict"
}
{
  "type": "invalid_request_error",
  "code": "cursor_expired",
  "message": "This cursor has expired. Start again without a cursor.",
  "status": 410,
  "param": "cursor",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#cursor-expired"
}
{
  "type": "validation_error",
  "code": "validation_failed",
  "message": "The selected product variant id is invalid.",
  "status": 422,
  "param": "product_variant_id",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#validation-failed",
  "errors": {
    "product_variant_id": [
      "The selected product variant id is invalid."
    ]
  }
}
{
  "type": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too Many Attempts.",
  "status": 429,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}
{
  "type": "api_error",
  "code": "api_error",
  "message": "Server Error",
  "status": 500,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#api-error"
}
GET
/v2/exports/{export}/download

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Path Parameters

export*string

The export identifier.

Formatuuid

Query Parameters

expires*integer

Expiry timestamp from the generated download URL.

signature*string

Copy the signature from the response-supplied download_url. The example is illustrative and cannot authorize a download.

Header Parameters

X-STORE?string

Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://sell.app/api/v2/exports/01992a65-e064-71ba-b38f-902b7966a6be/download?expires=1788513423&signature=2c91df645a086ec399153a932b741f809d2b85c69740eaf3612384ebfb913a65" \  -H "X-STORE: launch-lab"

No response body.

{
  "type": "invalid_request_error",
  "code": "bad_request",
  "message": "The request could not be understood.",
  "status": 400,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#bad-request"
}
{
  "type": "authentication_error",
  "code": "unauthenticated",
  "message": "Unauthenticated.",
  "status": 401,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}
{
  "type": "authorization_error",
  "code": "forbidden",
  "message": "This action is unauthorized.",
  "status": 403,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#forbidden"
}
{
  "type": "not_found_error",
  "code": "resource_not_found",
  "message": "Not Found.",
  "status": 404,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#resource-not-found"
}
{
  "type": "conflict_error",
  "code": "conflict",
  "message": "The resource state changed before this request.",
  "status": 409,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#conflict"
}
{
  "type": "invalid_request_error",
  "code": "cursor_expired",
  "message": "This cursor has expired. Start again without a cursor.",
  "status": 410,
  "param": "cursor",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#cursor-expired"
}
{
  "type": "validation_error",
  "code": "validation_failed",
  "message": "The selected product variant id is invalid.",
  "status": 422,
  "param": "product_variant_id",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#validation-failed",
  "errors": {
    "product_variant_id": [
      "The selected product variant id is invalid."
    ]
  }
}
{
  "type": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too Many Attempts.",
  "status": 429,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}
{
  "type": "api_error",
  "code": "api_error",
  "message": "Server Error",
  "status": 500,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#api-error"
}

Disputes

Read payment disputes across orders and standalone charges.

Overview

See what a customer bought, how they paid, and what happened to the order.