Error

A valid request URL is required to generate request examples

{
  "import": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "provider": "stripe",
    "provider_account_id": "<string>",
    "total": 123,
    "pending": 123,
    "created": 123,
    "mapped": 123,
    "matched": 123,
    "conflicts": 123,
    "failed": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "finished_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

Catalogue

Import the catalogue from a payment provider

Requires billing:write. Reads what this connection already sells at the gateway and turns it into plans, prices and their mappings here. Answers 202: the listing is accepted and durable, and none of it has been applied yet — a worker applies the lines in batches and the report fills in as it goes.

It is one-directional. Nothing here creates, renames or archives anything at the gateway: your catalogue is the source of truth for what you sell, the gateway is how it gets charged, and pushing rows outward would give one object two owners.

The connection has to be usable

A connection that is not connected refuses the import with 409 and the code provider_connection_not_ready — and the message names which repair that status calls for, because “not connected” is not something you can act on: invalid_credentials means paste a new key, mode_mismatch means paste the other key, and account_not_ready means the fix is in the gateway’s own dashboard and the key is fine. Run POST .../health first.

What a line does

A gateway product becomes a plan, named after the product and addressed by a handle derived from that name — Pro Anual becomes pro-anual. A plan’s key cannot be renamed afterwards, so it is derived rather than invented; a name that yields no usable handle falls back to the product’s own id, which is ugly and visibly the gateway’s own name for the thing.

A price becomes a catalogue price and is born mapped: it carries the gateway’s price id, so a checkout can charge it immediately. Outcomes per line are created (the price did not exist here), mapped (it did, said the same thing, and now knows how to be charged), matched (it was already imported — nothing was written), conflict and failed.

Running it twice is free. A gateway price that is already mapped is matched and nothing is written.

What it refuses to decide

A catalogue price cannot be edited — the money is what somebody agreed to pay — so an import never becomes an update. Where a line and this catalogue disagree, the line is reported and the repair is yours:

offer_taken — this plan already sells a live price for that currency and recurrence, at a different amount or a different tax behaviour. Choosing between two prices is a repricing, which is a commercial decision; use POST /v1/organization/catalogue/prices/{id}/reprice if that is what you meant.
plan_conflict — the product’s prices are already mapped onto one plan while the handle its name derives to belongs to another. Both plan ids are reported, because deciding which plan the product is takes a person.
already_mapped — the local price for that offer is already mapped to a different id at this gateway. Re-pointing it would silently move what a checkout charges.
product_spans_plans, plan_archived, mapped_price_disagrees, mapped_in_another_environment.

And a line this catalogue cannot hold is failed with the reason, never a guess: tax_behavior_unstated (whether an amount includes tax is an input only the person who typed it knows), no_unit_amount (a tiered or usage table is not one number), metered_price, usage_unstated, kind_unstated, unsupported_currency, product_unnamed, one_time_with_interval.

Nothing is charged and nothing is mailed

An import is a read followed by local writes.

POST

organization

environments

{id}

billing-providers

{provider}

catalogue-import

Error

A valid request URL is required to generate request examples

{
  "import": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "provider": "stripe",
    "provider_account_id": "<string>",
    "total": 123,
    "pending": 123,
    "created": 123,
    "mapped": 123,
    "matched": 123,
    "conflicts": 123,
    "failed": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "finished_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

Authorizations

Authorization

string

header

required

A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange.

Headers

X-Organization-Id

string

The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing. Absent, the session's default organization answers.

Path Parameters

string<uuid>

required

The environment's id.

provider

enum<string>

required

The payment gateway. stripe today. A gateway UserKit has no adapter for is refused here rather than stored, because a connection nothing can charge is discovered at somebody's checkout.

Available options:

stripe

Response

Accepted. Nothing has been applied yet — poll the import to watch it.

import

object

One import of a gateway's catalogue. Progress is derived from its lines on every read rather than accumulated as the worker goes — the tallies are a query, never a counter.

Show child attributes

Check a payment provider connection List catalogue imports

⌘I

Overview

Endpoints

Import the catalogue from a payment provider

The connection has to be usable

What a line does

What it refuses to decide

Nothing is charged and nothing is mailed

Authorizations

Headers

Path Parameters

Response