User API overview

This section is for Digital Stores: stores you opened as a regular PapelShip storefront (products, cart, checkout, customer panel). If you opened an API-based store to take payments on your own site, see the API-based Store tab instead.

The User API (called Store API in your dashboard) gives your servers the same control you have in the store dashboard: orders, products, stock, customers, support, shipping and webhooks. Base URL: https://app.papelship.com/api/v1

Older integrations that call https://app.papelship.com/api_user/api/v1 keep working. Use /api/v1 for new code.

Authenticate

Create a key in Developers › API keys and send it with your store ID on every request:

curl https://app.papelship.com/api/v1/me \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id"

GET /me works with any valid key. It returns the store, the key’s permissions and your limits, so use it to test your setup.

Keys act as the store owner. Keep them on your server, never in browser or mobile code.

Permissions

When you create a key, choose Full access, Read only or Custom. With Custom, you pick read or write access per area. Write includes read.

Area	Permission	Covers
Orders	`orders`	`/invoices`
Products	`products`	`/products` and everything under it
Categories & groups	`catalog`	`/categories`, `/groups`
Coupons	`coupons`	`/coupons`
Customers & blocklist	`customers`	`/customers`, `/blacklist`
Shipping & fulfilment	`fulfillment`	`/orders`, `/returns`, `/shipping`
Reviews	`reviews`	`/reviews`
Product questions	`questions`	`/questions`
Support tickets	`support`	`/tickets`
Subscriptions	`subscriptions`	`/subscriptions`
Affiliates	`affiliates`	`/affiliates`
Webhooks	`webhooks`	`/webhooks`, `/events`
Analytics	`analytics`	`/analytics` (read only)
Store	`store`	`/store`, `/payment-methods` (read only)

GET requests need read access; POST, PATCH, PUT and DELETE need write access. A key without the right permission gets 403 INSUFFICIENT_SCOPE with the missing permission in required_scope. You can also limit a key to this store, a list of IP addresses, or an expiry date.

Responses

Every response is JSON with a success flag.

Success

{ "success": true, "invoice": { "id": "c35ffd-19a1b2c3d4e-8c7a20", "status": "pending" } }

Error

{
  "success": false,
  "code": "VALIDATION_FAILED",
  "error": "customer_email must be a valid email address",
  "details": { "field": "customer_email" },
  "request_id": "req_7YbK2mQ9xP1cRt4v"
}

Branch on code, not on the message. Every response has an X-Request-Id header; include it when you contact support. See Errors for every code.

Conventions

Amounts are integers in minor units: price_cents: 2999 is 29.99.
Dates are ISO 8601 in UTC.
IDs are public IDs: product hash IDs, order IDs like c35ffd-19a1b2c3d4e-8c7a20. Records of other stores return 404.
Created records return 201.

Pagination

Lists take limit (1–100, default 25) and offset, and return a pagination object:

curl "https://app.papelship.com/api/v1/invoices?status=completed&limit=50&offset=100" \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id"

{
  "success": true,
  "invoices": [ ... ],
  "pagination": { "total": 342, "limit": 50, "offset": 100, "has_more": true }
}

Affiliate lists use a cursor instead: pass next_cursor back as cursor.

Safe retries

Send an Idempotency-Key header on create calls (orders, refunds, shipments, products, webhooks and others marked in the reference). If the network fails, retry with the same key and body: you get the first result back instead of a duplicate.

curl -X POST https://app.papelship.com/api/v1/invoices \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id" \
  -H "Idempotency-Key: 6f1c8a52-4f0e-4b8e-9a7c-2d1b3e5f7a90" \
  -H "Content-Type: application/json" \
  -d '{ "customer_email": "buyer@example.com", "items": [{ "product_id": "a1B2c3D4e5F6" }] }'

Keys are kept for 24 hours.
A replayed response has the header Idempotent-Replayed: true.
The same key with a different body returns 422 IDEMPOTENCY_KEY_REUSED.

Limits

Limit	Value	Headers
Requests per key	300 per minute	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix time)
Monthly calls	Depends on your plan	`X-Quota-Limit`

Over a limit you get 429 with Retry-After. RATE_LIMITED clears within a minute; STORE_API_MONTHLY_QUOTA_EXCEEDED resets on the first day of the next month (UTC). Every request appears in Developers › API requests with its status and duration.

Guides

Endpoints

Authenticate

Permissions

Responses

Conventions

Safe retries

Limits

Next steps

Create orders

Webhooks

​Authenticate

​Permissions

​Responses

​Conventions

​Pagination

​Safe retries

​Limits

​Next steps

Create orders

Webhooks

Authenticate

Permissions

Responses

Conventions

Pagination

Safe retries

Limits

Next steps