Transaction Export

Export your Sphere transaction data programmatically via CSV. The API uses an async job model: you create an export, poll for completion, and download the file via a presigned URL.

Prerequisites

• A Sphere account with an active billing provider connection (via the Integrations section of the app).

• An API key (see Settings > API Keys in the Sphere dashboard). The key must be included in every request header.

Authentication

All endpoints require an API key in the request header.

• Header Key: X-API-KEY

• Header Value: YOUR_API_KEY

Endpoints

1. Create Export

Starts an asynchronous export job. Returns a job_id that you use to poll for status.

URL: https://server.getsphere.com/tax_api/exports

Method: POST

Request Payload

Field	Type	Required	Description
date_range_start	string	Yes	Start date in YYYY-MM-DD format
date_range_end	string	Yes	End date in YYYY-MM-DD format
country_in	array of strings	No	Filter by country codes (e.g., ["US", "CA"]). Default: all countries
status_in	array of strings	No	Filter by transaction status (e.g., ["finalized", "paid"]). Default: all statuses
sources_in	array of strings	No	Filter by data source (e.g., ["stripe", "netsuite"]). Default: all sources
tax_authority_in	array of strings	No	Filter by tax authority keys (e.g., ["sc_us"]). Default: all regions
include_zero	boolean	No	Include zero-amount transactions. Default: true
processing	string	No	One of: "all", "processed", "unprocessed". Default: "all"

Request Example

curl -X POST https://server.getsphere.com/tax_api/exports \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date_range_start": "2025-01-01",
    "date_range_end": "2025-03-31",
    "status_in": ["finalized", "paid"],
    "country_in": ["US"]
  }'

Response (201 Created)

{
  "job_id": 12345,
  "status": "pending"
}

2. Get Export Status

Poll this endpoint to check whether your export is ready for download.

URL: https://server.getsphere.com/tax_api/exports/{job_id}

Method: GET

Request Example

curl https://server.getsphere.com/tax_api/exports/12345 \
  -H "X-API-KEY: YOUR_API_KEY"

Response — Pending or Running

{
  "job_id": 12345,
  "status": "pending",
  "created_at": "2025-03-20T10:30:00+00:00"
}

The status field will be one of: "pending", "running", "completed", or "failed".

Response — Completed

When the export is ready, the response includes a download_url — a presigned S3 URL that expires after 24 hours.

{
  "job_id": 12345,
  "status": "completed",
  "created_at": "2025-03-20T10:30:00+00:00",
  "completed_at": "2025-03-20T10:30:45+00:00",
  "download_url": "https://sphere-file-storage.s3.amazonaws.com/..."
}

Download the file by making a GET request to the download_url. No authentication header is needed for the download — the URL is self-authenticating.

Response — Failed

{
  "job_id": 12345,
  "status": "failed",
  "created_at": "2025-03-20T10:30:00+00:00",
  "error_message": "Export failed due to an internal error."
}

3. Cancel Export

Cancel a pending or in-progress export job.

URL: https://server.getsphere.com/tax_api/exports/{job_id}/cancel

Method: POST

Request Example

curl -X POST https://server.getsphere.com/tax_api/exports/12345/cancel \
  -H "X-API-KEY: YOUR_API_KEY"

Response (200 OK)

{
  "job_id": 12345,
  "status": "cancelled"
}

Note: Only jobs with status "pending" or "running" can be cancelled. Attempting to cancel a completed or failed job returns a 400 error.

Recommended Polling Strategy

After creating an export, poll the status endpoint at a reasonable interval:

1. POST /tax_api/exports → get job_id
2. Wait 2-5 seconds
3. GET /tax_api/exports/{job_id}
4. If status is "pending" or "running", go to step 2
5. If status is "completed", download the file from download_url
6. If status is "failed", handle the error

Most exports complete within a few seconds. Larger exports (many months of data across all regions) may take longer.

Rate Limits

You can have a maximum of 3 concurrent exports per organization. Jobs with status "pending" or "running" count toward this limit. Completed, failed, and cancelled jobs do not.

If you exceed this limit, the API returns a 429 error:

{
  "error": "Too many concurrent exports. Maximum 3 allowed."
}

CSV Columns

The exported CSV includes the following columns:

Column	Description
Invoice Id	Transaction identifier
Customer Id	Customer identifier from your billing system
Customer Name	Customer display name
Type	Transaction type (e.g., invoice, credit_note)
Line Item Id	Line item identifier
Status	Transaction status (finalized, paid, cancelled, etc.)
Transaction Source	Data source (e.g., stripe, netsuite)
Region	Tax jurisdiction name
Finalized On	Date the transaction was finalized
Paid On	Date the transaction was paid
Cancelled On	Date the transaction was cancelled
Event Date	Tax reporting date
Event Type	Tax reporting type (sale, refund)
Address	Customer address used for tax calculation
Description	Line item description
Product Name	Product display name
Product Tax Code	Tax code assigned to the product
Currency	Transaction currency code
Subtotal	Line item subtotal (in transaction currency)
Discount	Discount applied
Total	Line item total
Taxable Amount	Amount subject to tax
Total Tax Collected	Tax collected on the transaction
Sphere Calculated Tax	Tax amount calculated by Sphere
Filing Currency	Currency used for tax filing
Filing Exchange Rate	Exchange rate to filing currency
Filing Total	Total in filing currency
Filing Taxable Amount	Taxable amount in filing currency
Filing Total Tax Collected	Tax collected in filing currency
Filing Sphere Calculated Tax	Sphere-calculated tax in filing currency
Filing Status	Filing status for this transaction

The CSV also includes tax breakout columns for each jurisdiction level (Country, State, County, City, District, Transit Authority), each with Name, Tax Rate, and Tax Amount sub-columns.

Error Codes and Messages

1. Unauthorized Access

{
  "type": "api_error",
  "code": "unauthorized_access",
  "message": "Invalid API key."
}

Description: The API key provided in the request header is either missing or invalid.

Resolution: Verify that the API key is correctly included in the request headers. Ensure the key is correct, active, and authorized for this endpoint.

2. Missing Date Range

{
  "error": "date_range_start and date_range_end are required."
}

Description: One or both of the required date range fields are missing from the request body.

Resolution: Include both date_range_start and date_range_end in your request payload in YYYY-MM-DD format.

3. Invalid Date Format

{
  "error": "Invalid date format. Use YYYY-MM-DD."
}

Description: A date field could not be parsed.

Resolution: Ensure dates are in YYYY-MM-DD format (e.g., 2025-01-31).

4. Too Many Concurrent Exports

{
  "error": "Too many concurrent exports. Maximum 3 allowed."
}

Description: Your organization already has 3 exports in progress.

Resolution: Wait for an existing export to complete or cancel one, then retry.

5. Export Not Found

{
  "error": "Export job not found."
}

Description: The job_id does not exist or belongs to a different organization.

Resolution: Verify the job_id returned from the create endpoint.