{ "openapi": "3.1.0", "info": { "title": "Termpact Public API", "version": "1.0.0", "description": "REST API for ERPs and integrations. Authenticate with `Authorization: Bearer tp_live__`. Money is `{ amount_minor, currency }`; timestamps are RFC 3339 UTC; lists use `cursor` and `limit` (≤ 100). POST requests need an `Idempotency-Key` (replayed for 24 hours). Limits: 10 requests per second per key (burst 20) and 50,000 per day per shop; 429 carries `Retry-After`. Errors are RFC 9457 problem details." }, "servers": [ { "url": "https://app.termpact.com/api/v1" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Scopes: pricing:read, pricing:write, locations:write, ledger:read, payments:write" } }, "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "examples": [ "https://help.termpact.com/api/errors/validation_failed" ] }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "x-problem-types": { "https://help.termpact.com/api/errors/not_found": { "status": 404, "title": "Not found" }, "https://help.termpact.com/api/errors/method_not_allowed": { "status": 405, "title": "Method not allowed" }, "https://help.termpact.com/api/errors/validation_failed": { "status": 422, "title": "The request is not valid" }, "https://help.termpact.com/api/errors/insufficient_scope": { "status": 403, "title": "The API key lacks a required scope" }, "https://help.termpact.com/api/errors/plan_required": { "status": 403, "title": "The Public API needs the Pro plan" }, "https://help.termpact.com/api/errors/read_only": { "status": 402, "title": "Billing is inactive; the API is read-only" }, "https://help.termpact.com/api/errors/shop_read_only": { "status": 503, "title": "This store is read-only while Termpact checks a problem" }, "https://help.termpact.com/api/errors/conflict": { "status": 409, "title": "Conflict" }, "https://help.termpact.com/api/errors/idempotency_key_required": { "status": 400, "title": "Idempotency-Key header is required" }, "https://help.termpact.com/api/errors/idempotency_key_reused": { "status": 422, "title": "Idempotency-Key reused with a different request" }, "https://help.termpact.com/api/errors/idempotency_in_progress": { "status": 409, "title": "A request with this Idempotency-Key is still running" }, "https://help.termpact.com/api/errors/payload_too_large": { "status": 413, "title": "Request body too large" }, "https://help.termpact.com/api/errors/unsupported_media_type": { "status": 415, "title": "Content-Type must be application/json" }, "https://help.termpact.com/api/errors/rate_limited": { "status": 429, "title": "Too many requests" }, "https://help.termpact.com/api/errors/unavailable": { "status": 503, "title": "Service unavailable" } }, "paths": { "/price-groups": { "get": { "operationId": "listPriceGroups", "summary": "List price groups", "tags": [ "Price groups" ], "security": [ { "apiKey": [ "pricing:read" ] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "base_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "rounding": { "type": "string", "enum": [ "none", "r99", "r95", "r05" ] }, "exclude_sale_items": { "type": "boolean" }, "min_margin_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "active_from": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "active_to": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "notice_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "name", "status", "base_bp", "rounding", "exclude_sale_items", "min_margin_bp", "active_from", "active_to", "notice_days" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createPriceGroup", "summary": "Create a price group", "tags": [ "Price groups" ], "security": [ { "apiKey": [ "pricing:write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "base_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "rounding": { "type": "string", "enum": [ "none", "r99", "r95", "r05" ] }, "exclude_sale_items": { "type": "boolean" }, "min_margin_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "active_from": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "active_to": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "notice_days": { "type": "integer", "minimum": 0, "maximum": 90 }, "status": { "type": "string", "enum": [ "draft", "active" ] } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "base_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "rounding": { "type": "string", "enum": [ "none", "r99", "r95", "r05" ] }, "exclude_sale_items": { "type": "boolean" }, "min_margin_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "active_from": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "active_to": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "notice_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "name", "status", "base_bp", "rounding", "exclude_sale_items", "min_margin_bp", "active_from", "active_to", "notice_days" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/price-groups/{code}": { "get": { "operationId": "getPriceGroup", "summary": "Get a price group", "tags": [ "Price groups" ], "security": [ { "apiKey": [ "pricing:read" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "base_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "rounding": { "type": "string", "enum": [ "none", "r99", "r95", "r05" ] }, "exclude_sale_items": { "type": "boolean" }, "min_margin_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "active_from": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "active_to": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "notice_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "name", "status", "base_bp", "rounding", "exclude_sale_items", "min_margin_bp", "active_from", "active_to", "notice_days" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updatePriceGroup", "summary": "Change a price group's settings or status", "tags": [ "Price groups" ], "security": [ { "apiKey": [ "pricing:write" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "base_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "rounding": { "type": "string", "enum": [ "none", "r99", "r95", "r05" ] }, "exclude_sale_items": { "type": "boolean" }, "min_margin_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "active_from": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "active_to": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "notice_days": { "type": "integer", "minimum": 0, "maximum": 90 }, "status": { "type": "string", "enum": [ "draft", "active" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "base_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "rounding": { "type": "string", "enum": [ "none", "r99", "r95", "r05" ] }, "exclude_sale_items": { "type": "boolean" }, "min_margin_bp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "active_from": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "active_to": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "notice_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "name", "status", "base_bp", "rounding", "exclude_sale_items", "min_margin_bp", "active_from", "active_to", "notice_days" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deletePriceGroup", "summary": "Archive a price group that no company location uses", "tags": [ "Price groups" ], "security": [ { "apiKey": [ "pricing:write" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "responses": { "204": { "description": "No content" }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/price-groups/{code}/rules": { "get": { "operationId": "listRules", "summary": "The group's ordered percentage rules (first match wins)", "tags": [ "Price groups" ], "security": [ { "apiKey": [ "pricing:read" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "collection", "vendor", "type", "tag" ] }, "ref": { "type": "string", "minLength": 1, "maxLength": 255 }, "value_bp": { "type": "integer", "minimum": 0, "maximum": 10000 }, "code": { "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "scope", "ref", "value_bp", "code", "position" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "operationId": "replaceRules", "summary": "Replace the ordered rule list in one write", "tags": [ "Price groups" ], "security": [ { "apiKey": [ "pricing:write" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "maxItems": 300, "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "collection", "vendor", "type", "tag" ] }, "ref": { "type": "string", "minLength": 1, "maxLength": 255 }, "value_bp": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "scope", "ref", "value_bp" ] } } }, "required": [ "rules" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "collection", "vendor", "type", "tag" ] }, "ref": { "type": "string", "minLength": 1, "maxLength": 255 }, "value_bp": { "type": "integer", "minimum": 0, "maximum": 10000 }, "code": { "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "scope", "ref", "value_bp", "code", "position" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/price-groups/{code}/volume-breaks": { "get": { "operationId": "listVolumeBreaks", "summary": "The group's volume breaks", "tags": [ "Price groups" ], "security": [ { "apiKey": [ "pricing:read" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "variant", "product" ] }, "id": { "type": "string" }, "count_mode": { "type": "string", "enum": [ "variant", "product" ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "min_qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "prices": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Z]{3}$" }, "additionalProperties": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } } }, "required": [ "min_qty", "prices" ], "additionalProperties": false } } }, "required": [ "target", "id", "count_mode", "tiers" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "operationId": "setVolumeBreaks", "summary": "Set (or remove with tiers: null) the breaks of one variant or product, ≤ 10 tiers", "tags": [ "Price groups" ], "security": [ { "apiKey": [ "pricing:write" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "object", "properties": { "variant_id": { "type": "string", "pattern": "^\\d{1,20}$" } }, "required": [ "variant_id" ], "additionalProperties": false }, { "type": "object", "properties": { "product_id": { "type": "string", "pattern": "^\\d{1,20}$" } }, "required": [ "product_id" ], "additionalProperties": false } ] }, "count_mode": { "default": "variant", "type": "string", "enum": [ "variant", "product" ] }, "tiers": { "anyOf": [ { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "min_qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "prices": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Z]{3}$" }, "additionalProperties": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } } }, "required": [ "min_qty", "prices" ] } }, { "type": "null" } ] } }, "required": [ "target", "tiers" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "target": { "type": "string", "enum": [ "variant", "product" ] }, "id": { "type": "string" }, "count_mode": { "type": "string", "enum": [ "variant", "product" ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "min_qty": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "prices": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Z]{3}$" }, "additionalProperties": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } } }, "required": [ "min_qty", "prices" ], "additionalProperties": false } } }, "required": [ "target", "id", "count_mode", "tiers" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/price-groups/{code}/fixed-prices/import": { "post": { "operationId": "importFixedPrices", "summary": "Import fixed prices from CSV (variant_id or sku, currency, price); dry_run=true returns the diff only", "tags": [ "Price groups" ], "security": [ { "apiKey": [ "pricing:write" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "minLength": 1, "maxLength": 5000000 }, "mode": { "default": "merge", "type": "string", "enum": [ "merge", "replace" ] } }, "required": [ "csv" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "adds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updates": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "removals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "message": { "type": "string" } }, "required": [ "line", "message" ], "additionalProperties": false } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "message": { "type": "string" } }, "required": [ "line", "message" ], "additionalProperties": false } } }, "required": [ "dry_run", "rows", "adds", "updates", "removals", "errors", "warnings" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/locations": { "get": { "operationId": "listLocations", "summary": "Company locations with their price group and credit standing", "tags": [ "Locations" ], "security": [ { "apiKey": [ "pricing:read" ] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "currency": { "type": [ "string", "null" ] }, "price_group": { "type": [ "string", "null" ] }, "credit": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string" }, "limit_minor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "exposure_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "ok", "soft_hold", "hard_hold", "pending" ], "description": "pending: the limit was just saved and the balance is still being worked out (usually seconds)" }, "overdue_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "currency", "limit_minor", "exposure_minor", "status", "overdue_days" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "name", "company", "currency", "price_group", "credit" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/locations/{location_id}/assignment": { "put": { "operationId": "setLocationAssignment", "summary": "Set a location's price group and/or credit limit, currency and mode", "tags": [ "Locations" ], "security": [ { "apiKey": [ "locations:write" ] } ], "parameters": [ { "name": "location_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "price_group": { "anyOf": [ { "type": "string", "pattern": "^g[1-9]\\d{0,8}$" }, { "type": "null" } ] }, "credit": { "type": "object", "properties": { "limit_minor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "default": null, "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] }, "mode": { "default": "soft", "type": "string", "enum": [ "soft", "hard" ] }, "overdue_hold_days": { "default": null, "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 365 }, { "type": "null" } ] } }, "required": [ "limit_minor" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "currency": { "type": [ "string", "null" ] }, "price_group": { "type": [ "string", "null" ] }, "credit": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string" }, "limit_minor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "exposure_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "ok", "soft_hold", "hard_hold", "pending" ], "description": "pending: the limit was just saved and the balance is still being worked out (usually seconds)" }, "overdue_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "currency", "limit_minor", "exposure_minor", "status", "overdue_days" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "name", "company", "currency", "price_group", "credit" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/locations/{location_id}/balance": { "get": { "operationId": "getLocationBalance", "summary": "Open and overdue amounts per currency, unapplied credit and the credit standing", "tags": [ "Locations" ], "security": [ { "apiKey": [ "ledger:read" ] } ], "parameters": [ { "name": "location_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "string" }, "as_of": { "type": "string" }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "open": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "overdue": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "overdue_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unapplied_credit": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "oldest_overdue_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "next_due": { "anyOf": [ { "type": "object", "properties": { "date": { "type": "string" }, "amount": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false } }, "required": [ "date", "amount" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "currency", "open", "overdue", "overdue_count", "unapplied_credit", "oldest_overdue_days", "next_due" ], "additionalProperties": false } }, "credit": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "limit": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, { "type": "null" } ] }, "exposure": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "available": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "status", "limit", "exposure", "available" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "location_id", "as_of", "currencies", "credit" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/ledger": { "get": { "operationId": "listLedgerEntries", "summary": "Ledger entries of a location, oldest first, with their allocations", "tags": [ "Ledger" ], "security": [ { "apiKey": [ "ledger:read" ] } ], "parameters": [ { "name": "location", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,20}$" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "amount": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "status": { "type": [ "string", "null" ] }, "location_id": { "type": "string" }, "order_id": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "created_at": { "type": "string" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "payment_id": { "type": "string" }, "amount": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false } }, "required": [ "payment_id", "amount" ], "additionalProperties": false } } }, "required": [ "id", "type", "amount", "status", "location_id", "order_id", "due_date", "source", "created_at", "allocations" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices": { "get": { "operationId": "listInvoices", "summary": "Invoices, newest first; filter by location and status (default: every status except superseded)", "tags": [ "Ledger" ], "security": [ { "apiKey": [ "ledger:read" ] } ], "parameters": [ { "name": "location", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{1,20}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "partially_paid", "paid", "disputed", "written_off", "refunded", "cancelled", "superseded" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" }, "location_id": { "type": "string" }, "company_id": { "type": "string" }, "order_id": { "type": [ "string", "null" ] }, "amount": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "open": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "due_date": { "type": [ "string", "null" ] }, "issued_at": { "type": "string" } }, "required": [ "id", "number", "status", "location_id", "company_id", "order_id", "amount", "open", "due_date", "issued_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "One invoice with a PDF link valid for 10 minutes", "tags": [ "Ledger" ], "security": [ { "apiKey": [ "ledger:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" }, "location_id": { "type": "string" }, "company_id": { "type": "string" }, "order_id": { "type": [ "string", "null" ] }, "amount": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "open": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "due_date": { "type": [ "string", "null" ] }, "issued_at": { "type": "string" }, "pdf": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "url", "expires_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "location_id", "company_id", "order_id", "amount", "open", "due_date", "issued_at", "pdf" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/payments": { "get": { "operationId": "listPayments", "summary": "Payments, newest first", "tags": [ "Ledger" ], "security": [ { "apiKey": [ "ledger:read" ] } ], "parameters": [ { "name": "location", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{1,20}$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "location_id": { "type": "string" }, "method": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "amount": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "status": { "type": "string" }, "received_at": { "type": "string" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "amount": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false } }, "required": [ "invoice_id", "amount" ], "additionalProperties": false } }, "unapplied": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false } }, "required": [ "id", "location_id", "method", "reference", "amount", "status", "received_at", "allocations", "unapplied" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "recordPayment", "summary": "Record a payment received outside Shopify; allocations explicit or auto (oldest first, the rest is unapplied credit)", "tags": [ "Ledger" ], "security": [ { "apiKey": [ "payments:write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "string", "pattern": "^\\d{1,20}$" }, "amount_minor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "received_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "method": { "type": "string", "enum": [ "bank_transfer", "cheque", "cash", "other" ] }, "reference": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "allocations": { "default": "auto", "anyOf": [ { "type": "string", "const": "auto" }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "invoice_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "amount_minor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "invoice_id", "amount_minor" ], "additionalProperties": false } } ] } }, "required": [ "location_id", "amount_minor", "currency", "received_date", "method" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "location_id": { "type": "string" }, "method": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "amount": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "status": { "type": "string" }, "received_at": { "type": "string" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "amount": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false } }, "required": [ "invoice_id", "amount" ], "additionalProperties": false } }, "unapplied": { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false } }, "required": [ "id", "location_id", "method", "reference", "amount", "status", "received_at", "allocations", "unapplied" ], "additionalProperties": false } } } }, "default": { "description": "Problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } } }