Process CartAPI

OpenAPI

The OpenAPI 3.1 document — JSON and YAML, generated from the same schemas the API validates with — and how to use it for code generation.

View this page as Markdown

The whole API is described by one OpenAPI 3.1 document, generated from the request and response schemas the server validates with, so it cannot drift from the code:

Both are served live; the same document is browsable in the interactive reference.

What is in it

  • Every operation with its operationId, parameters, request body, every response status it can answer and the exact error code list per status — the same list the contract tests hold the routes to.
  • Every component schema (Run, RunField, Problem, …), with growable enums marked x-processcart-open-enum: true.
  • The security schemes (bearerAuth, apiKeyHeader), the request headers Idempotency-Key and Expected-Revision, and the response headers: X-Request-Id, RateLimit-*, Retry-After, Idempotent-Replayed, Location, Deprecation, Sunset.
  • Worked request and response examples captured from real responses by the contract tests, redacted.
  • The webhooks object: one entry per event type with the Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature, x-processcart-event), the envelope and the per-event data schema, and the retry schedule.
  • Vendor extensions: x-processcart-scope (the scope an operation needs), x-processcart-allowlist, x-processcart-paginated, x-processcart-idempotency-key, and on info the rate limit and the webhook retry minutes.

servers is https://app.processcart.com/api and every path starts with /v1.

Generating a client

The document validates against the OpenAPI 3.1 meta-schema and works with the usual generators — openapi-typescript, openapi-generator, kiota, Postman and Insomnia imports. Keep three conventions in mind:

  • Problem responses are application/problem+json; the Problem schema is shared by every error status, narrowed per operation to the codes it can answer.
  • Field values are typed per field at runtime (GET /v1/workflows/{id}/schema), not in the static document: RunField.value is the union of every canonical shape. Generate the per-workflow schema when you need exact types.
  • Open enums: generate them as strings (or add an "unknown" arm) so a new status or event type does not break deserialization.

The official TypeScript SDK, @processcart/sdk, is typed from this document (its types and operations table are generated from it; the methods are written against them): one typed method per operation, plus cursor pagination, idempotency keys, retries and webhook signature verification.