Get started

Billing

The account behind the maps: what can be bought, what the organization holds, the card it is charged on, and the invoices it has been sent. Every operation here needs a session token beside the key.

The BillingInfo object

The billing information held for an organization: the name and email an invoice is addressed to, the billing address, and the tax identifier when one is registered. The address is absent when none is on file, and so is the tax identifier.

name

string

required

The name an invoice is addressed to. It starts as the organization's own name and is changed through the billing information update. Never empty: an update that sends an empty name restores the organization's own rather than clearing this. The ceiling is the update's hundred characters rather than the thirty an organization name is held to, because a payer is a legal entity and the two are not the same field.

email

string (email)

required

The address invoices and payment notices are sent to. It starts as the email address of the member who opened billing, which on this API is the user the session token names on postOrganizationBillingProvision, and is changed through the billing information update.

address

object

The billing address. Absent when none is on file. While none is, saving a card fills it from the card's billing address, when the card carries one.

tax_id

object

The tax identifier registered against the account, such as an EU VAT number. Absent when none is registered.

The OrganizationSubscriptionSummary object

An organization's subscription, as the billing operations report it. api is the metered Data API subscription, billed by the month on the Data API requests the organization makes, and the one subscription an operation in this contract opens: the organization's first saved card opens it, unless the customer, or that card, still owes an invoice, which is the 402 and opens nothing, and the organization holds data while it is in force. Opening billing opens nothing, so an organization has no summary at all until its first card has opened that subscription. One that has ended is still reported, with the status it ended on. What an organization's agreement with Mountaya grants, Map Studio, Map Publishing, the Tile API, Embedded Studio and White label, is not a subscription and is never reported here.

api

object

The metered Data API subscription. It carries the Data API line, which bills the requests the organization makes, the MCP server's included, at the end of each billing period, a month counted from the day the subscription opened. A line's price says nothing a client should read a product from: organization_capabilities on getMyOrganizations says which products the organization holds. An organization that has never held one, as before its first card opens it, gets no summary at all rather than a summary without it. It is also where a Data API subscription Mountaya arranged separately for the organization is reported, which no operation in this contract opens: only such a one is read on a trial, billed by invoice, or with a line on the tiles dimension.

has_payment_method

boolean

Whether the organization has a default payment method, which is what the metered use of the Data API needs: a key's Data API request answers 402 while the subscription is in force and no payment method is on file. It is what lets a client ask for a card before that happens. It says nothing about the subscription beside it: a default payment method can be on file while no subscription is in force, as when one has ended, and a card saved without becoming the default leaves it false. Present whenever a summary is returned. An organization that has never held a subscription gets no summary at all, whether or not it has saved a card: getOrganizationBillingPaymentMethods is the read for that.

The PaymentMethod object

A payment method saved against the organization's billing account. type says which instrument it is and which sub-object is present: card carries card, and sepa_debit carries sepa_debit. is_default marks the one invoices and subscriptions charge; at most one saved method carries it, and none does until a default has been chosen.

id

string

required

Identifier of the payment method. It is what names the method when making it the default or detaching it. Opaque, and issued by the payment provider rather than by Mountaya, so do not parse it as a UUID the way every id Mountaya issues can be. It is the same pm_ identifier the payment_method_id path parameter takes.

type

string

required

Which instrument the method is, in the payment provider's own words, and so an open set rather than an enum: card and sepa_debit are the two that carry a sub-object below. A method of any other kind is listed too, with neither sub-object, so a client that can only show those two reads this to skip the rest rather than failing on it.

is_default

boolean

required

Whether this is the method invoices and subscriptions charge.

card

object

The card's display details. Present only when type is card.

sepa_debit

object

The mandate's display details. Present only when type is sepa_debit.

List the billing catalog

Returns what an organization can buy: one entry per unit of access, with the capabilities it grants, how it is counted, and the price it is sold on. It is the catalog a client builds a checkout from, so the figures it shows are the ones that will be charged rather than a copy kept in step by hand. The Data API is the one product sold this way, metered by the month on the requests made, and the first card an organization saves is what opens it, unless the customer, or that card, still owes an invoice, which is the 402 and opens nothing. Map Studio, Map Publishing, the Tile API, Embedded Studio and White label are granted by an organization's agreement with Mountaya and are not in the catalog.

  • The catalog is the same for every organization, and it asks no member role, so a session token is answered alike whoever it names, or, minted for api, with no user at all; one minted for studio-embedded naming nobody is a 401. A product with no price set is left out rather than returned without one, so an entry that is here is one that can be bought. A product whose prices cannot be read from the payment provider at the moment is still listed, with prices empty: read that as an amount unavailable, not as a product that cannot be bought.
  • It is a catalog, not a listing of what an organization made, so it is not paged: every product comes back at once.

Response 200

The catalog, one entry per unit of access that can be bought.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

array of BillingProduct

required

Errors 400, 401, 403, 429, 500, 504. See Errors.

curl -s https://api.mountaya.com/v1/billing/products \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": [
    {
      "key": "data",
      "label": "Data API",
      "granted_capabilities": [
        "data"
      ],
      "unit_kind": "per-request",
      "contact_sales_only": false,
      "prices": [
        {
          "unit_amount": null,
          "currency": "eur",
          "interval": "month",
          "metered": true
        }
      ]
    }
  ]
}

Open an organization's billing

POST
/v1/organizations/{organization_id}/billing/provision

Opens the organization's billing account, which collecting a card needs, records the promotion code it is given, and returns the billing information invoices will be addressed to. It opens no subscription, raises no invoice and charges nothing. The Data API is the one product an organization obtains by card: the first card saved through postOrganizationBillingPaymentMethodSetup and postOrganizationBillingPaymentMethod opens the metered Data API subscription, billed by the month on the requests the organization makes, and from then the organization holds data. Until then it holds no product and owes nothing. Map Studio, Map Publishing, the Tile API, Embedded Studio and White label are granted by the organization's agreement with Mountaya, and no card opens any of them.

  • Owner or admin only (403 otherwise), and refused for an organization whose billing is settled by its agreement with Mountaya (403).
  • Until the first card, a key carrying data or mcp answers 402 wherever it is used.
  • promotion_code is kept for the organization's first Data API subscription and applied when the first card opens it. The last call decides: a call carrying another code replaces the one recorded, and a call carrying none clears it.
  • A promotion_code this organization cannot use is a 400 naming the field, and nothing is created or recorded. That includes every code given to an organization that has already held a Data API subscription: a code applies to the first one only, and a call carrying none still succeeds. One accepted here that the payment provider refuses as it is redeemed is answered by the call that would have opened the subscription: postOrganizationBillingPaymentMethod for a card, or postOrganizationBillingSubscription on the default payment method.
  • The billing information starts with the organization's own name and the email address of the user the session token names. Change either with patchOrganizationBillingInfo.
  • Safe to repeat: a double-submit or a retry opens no second account, and two calls sent at the same moment open one billing account. A call on an organization whose billing is already open records the promotion code it carries, or clears it, and answers the billing information as it stands.
  • The subscription the first card opens bills by the month, in arrears, on what the organization used. There is no interval to choose, here or afterwards.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Body

A promotion code to keep for the organization's first Data API subscription. It is optional: an empty object records none, and clears one recorded by an earlier call.

promotion_code

string

in body

A promotion code for the organization's first Data API subscription, as it was handed to the customer. It is checked against this organization, so a code restricted to another customer is refused with a 400, and so is any code given to an organization that has already held a Data API subscription, which no code applies to. An accepted one is recorded, and applied when the first card opens the subscription. Omitted, none is recorded, and one recorded by an earlier call is cleared. Letters, digits, hyphens and underscores, at most 64, the form a code takes wherever it is read.

Response 200

Billing is open, by this call or an earlier one: data is the organization's billing information, as getOrganizationBillingInfo reads it, and the promotion code the call gave, if any, is recorded. No subscription is opened by this.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

BillingInfo

required

The billing information held for an organization: the name and email an invoice is addressed to, the billing address, and the tax identifier when one is registered. The address is absent when none is on file, and so is the tax identifier.

See the BillingInfo object.

Errors 400, 401, 403, 404, 409, 413, 429, 500, 503, 504. See Errors.

curl -s -X POST https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/provision \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"promotion_code": "EARLYGUIDE"}'
200
Response
{
  "data": {
    "name": "Compagnie des Guides",
    "email": "billing@example.com",
    "address": {
      "line1": "190 place de l'Église",
      "city": "Chamonix-Mont-Blanc",
      "postal_code": "74400",
      "country": "FR"
    },
    "tax_id": {
      "type": "eu_vat",
      "value": "FR40303265045"
    }
  }
}

Retrieve an organization's subscription

GET
/v1/organizations/{organization_id}/billing/subscription

Returns the organization's subscription: the metered Data API subscription, billed by the month on the Data API requests the organization makes, which is the one subscription an operation in this contract opens. It is the read to branch a Data API payment refusal on: has_payment_method says whether a default payment method is on file, and the subscription's status, read with its paused flag, says whether what it grants is in force. What an agreement with Mountaya grants is not a subscription and is not reported here, so an organization whose billing its agreement settles can read data null too, and is never asked for a card. For an owner or an admin of the key's organization, a 403 from postOrganizationBillingProvision, postOrganizationBillingPaymentMethodSetup or postOrganizationBillingPaymentMethod means exactly that: billing is settled by the agreement, and no card is asked for.

  • A session token minted for api without a user is what authorizes this read, and no member role is checked on top of it; one minted for studio-embedded without a user is the 401 a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. The path names the key's own organization: another is a 403, whether or not it exists.
  • data is null for an organization that has never held a subscription, which is where an organization stands until its first card opens its Data API subscription: opening billing opens none, and a card that is still processing leaves it null with the card saved. A subscription that has ended stays in its slot with the status it ended on, so api reads status: canceled once the Data API subscription has ended.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Response 200

The organization's subscription. data is null when the organization has never held one, and a subscription that has ended stays in its slot with the status it ended on.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

OrganizationSubscriptionSummary | null

required

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

curl -s https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/subscription \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": {
    "has_payment_method": true,
    "api": {
      "status": "active",
      "collection_method": "charge-automatically",
      "currency": "eur",
      "current_period_end_at": "2026-09-01T02:14:07Z",
      "cancel_at_period_end": false,
      "paused": false,
      "items": [
        {
          "price_id": "price_1QeDataRequests",
          "quantity": 1,
          "meter": "data"
        }
      ]
    }
  }
}

Run an organization's Data API subscription

POST
/v1/organizations/{organization_id}/billing/subscription

Runs the organization's metered Data API subscription, whatever state it is in, and returns it.

  • An end scheduled by deleteOrganizationBillingSubscription is taken back, and the subscription carries on into its next period.
  • A subscription that is past due or unpaid has its outstanding invoices charged to the organization's default payment method, as saving a card charges them. A charge the card refuses does not fail the call: the subscription is returned as the charge left it. With no default payment method on file there is nothing to charge, and it is returned as it is.
  • A paused subscription is returned as it is, and nothing changes.
  • A subscription already running is returned as it is, and nothing changes.
  • Where the organization holds none, because the one it held has ended, its agreement with Mountaya has ended, or it never held one, one is opened on the organization's default payment method, exactly as the first card opens one: billed by the month on the requests the organization makes, with tax. From then the organization holds data. The promotion code recorded by postOrganizationBillingProvision applies only to the organization's first Data API subscription.
  • With no default payment method on file, or no billing account, the answer is a 402 and nothing is opened. Saving a card through postOrganizationBillingPaymentMethodSetup and postOrganizationBillingPaymentMethod opens the subscription on its own.
  • Before one is opened, every invoice the organization still owes, open or uncollectible, those of a subscription that has ended included, is collected on the default payment method. When one cannot be collected on it, the answer is a 402 and nothing is opened: the organization does not start a new subscription while it owes for an earlier one. Pay what is owed, or make a card that can pay it the default, and call this again.
  • Nor is one opened on a default card another organization still owes on. A card is recognized by its number, whichever organization saved it, and while any other organization owes an invoice that a payment on a card of the same number failed to pay, one marked uncollectible or one still open after that attempt, the answer is the same 402 and nothing is opened. Only what the card itself failed to pay refuses it: a card the other organization merely has on file, or used to pay something else, blocks nothing, and neither does an invoice whose payment is still processing. Nothing the other organization owes is charged here: it is settled on that organization.
  • The subscription's invoices are taxed. When the payment provider cannot tell where the organization is taxed, the answer is a 400 whose entry names no field, since nothing in this request is what is missing; its message asks for a billing address. Nothing is opened. Set one with patchOrganizationBillingInfo and call this again.
  • When the payment provider refuses the default payment method as the subscription opens, the answer is a 400 whose entry names no field, and nothing is opened. The refusal is remembered for a day: calling this again while the same method is the default is answered the same 400. Make another saved method the default with postOrganizationBillingPaymentMethodSetDefault and call this again, or save another card, which opens the subscription on its own. Each method is an attempt of its own, and a card saved again is a new method, so it is one too.
  • When the promotion code recorded by postOrganizationBillingProvision for the organization's first Data API subscription is refused by the payment provider as it is redeemed, expired or used up since it was recorded, the answer is a 400 whose entry names no field, since the code is no part of this request. Nothing is opened or charged. Call postOrganizationBillingProvision again with another code, or with none, then call this again.
  • Owner or admin only (403 otherwise), and refused for an organization whose billing is settled by its agreement with Mountaya (403).
  • Calling it again changes nothing for a subscription that runs or is paused. One that is past due or unpaid is charged again: each call charges its outstanding invoices to the default payment method, so a call repeated after a refusal is another attempt on that method. An invoice already paid is not charged twice.

Webhook events organization.billing.subscription.created, organization.billing.subscription.updated, recorded by the task organization.billing.subscription.run.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Response 200

The Data API subscription is running: cancel_at_period_end is false, and api is the subscription opened where none was held. A paused subscription is returned as it is, still paused, and one past due or unpaid as the charge of its outstanding invoices left it.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

OrganizationSubscriptionSummary

required

An organization's subscription, as the billing operations report it. api is the metered Data API subscription, billed by the month on the Data API requests the organization makes, and the one subscription an operation in this contract opens: the organization's first saved card opens it, unless the customer, or that card, still owes an invoice, which is the 402 and opens nothing, and the organization holds data while it is in force. Opening billing opens nothing, so an organization has no summary at all until its first card has opened that subscription. One that has ended is still reported, with the status it ended on. What an organization's agreement with Mountaya grants, Map Studio, Map Publishing, the Tile API, Embedded Studio and White label, is not a subscription and is never reported here.

See the OrganizationSubscriptionSummary object.

Errors 400, 401, 402, 403, 404, 409, 429, 500, 503, 504. See Errors.

curl -s -X POST https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/subscription \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": {
    "has_payment_method": true,
    "api": {
      "status": "active",
      "collection_method": "charge-automatically",
      "currency": "eur",
      "current_period_end_at": "2026-09-01T02:14:07Z",
      "cancel_at_period_end": false,
      "paused": false,
      "items": [
        {
          "price_id": "price_1QeDataRequests",
          "quantity": 1,
          "meter": "data"
        }
      ]
    }
  }
}

End an organization's Data API subscription at the end of its period

DELETE
/v1/organizations/{organization_id}/billing/subscription

Ends the organization's metered Data API subscription when its current period does. Nothing changes before then: the organization keeps data, its requests are still counted, and the period is invoiced at its end, as every period is, its usage up to the moment it ends included, its last day among it. The subscription then ends, and from then the organization does not hold data.

  • Owner or admin only (403 otherwise), and refused for an organization whose billing is settled by its agreement with Mountaya (403). An agreement ends a subscription the organization still holds at the end of its period on its own.
  • The subscription is returned with cancel_at_period_end true, and current_period_end_at the moment it ends.
  • An organization that holds no Data API subscription, or only one that has ended, has nothing to end. It is answered 200 with the subscription as getOrganizationBillingSubscription reads it, data null where it never held one, and nothing changes.
  • postOrganizationBillingSubscription takes the end back while the period runs, and runs the Data API again once it has ended.
  • Calling it again changes nothing: an end already scheduled is answered as it stands.

Webhook events organization.billing.subscription.updated, recorded by the task organization.billing.subscription.cancel.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Response 200

The end is scheduled, or there was nothing to end. A subscription in force reads cancel_at_period_end true and ends at current_period_end_at. One that has ended is returned as it ended, and data is null for an organization that has never held one.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

OrganizationSubscriptionSummary | null

required

Errors 400, 401, 403, 404, 409, 429, 500, 503, 504. See Errors.

curl -s -X DELETE https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/subscription \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": {
    "has_payment_method": true,
    "api": {
      "status": "active",
      "collection_method": "charge-automatically",
      "currency": "eur",
      "current_period_end_at": "2026-09-01T02:14:07Z",
      "cancel_at_period_end": true,
      "paused": false,
      "items": [
        {
          "price_id": "price_1QeDataRequests",
          "quantity": 1,
          "meter": "data"
        }
      ]
    }
  }
}

Retrieve an organization's billing information

GET
/v1/organizations/{organization_id}/billing/info

Returns what an invoice is addressed to: the name, the email, the billing address when one is on file, and the tax identifier when one is registered. Read it against the same object patchOrganizationBillingInfo writes: this is the whole of what that operation changes.

  • A session token minted for api without a user is what authorizes this read, and no member role is checked on top of it; one minted for studio-embedded without a user is the 401 a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. The path names the key's own organization: another is a 403, whether or not it exists.
  • data is null for an organization that has no billing account yet, which postOrganizationBillingProvision opens: there is nothing to address an invoice to until then.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Response 200

What invoices for this organization are addressed to, or data null when the organization has no billing account yet.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

BillingInfo | null

required

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

curl -s https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/info \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": {
    "name": "Compagnie des Guides",
    "email": "billing@example.com",
    "address": {
      "line1": "190 place de l'Église",
      "city": "Chamonix-Mont-Blanc",
      "postal_code": "74400",
      "country": "FR"
    },
    "tax_id": {
      "type": "eu_vat",
      "value": "FR40303265045"
    }
  }
}

Update an organization's billing information

PATCH
/v1/organizations/{organization_id}/billing/info

Writes what invoices are addressed to, and returns the whole record after the change. Every field is optional and every field present is a replacement: an omitted field is left alone, an address whose fields are all empty clears the address, and a tax_id with an empty value clears the tax identifier. Sending name as the empty string restores the organization's own name rather than clearing it.

  • Owner or admin only (403 otherwise), and refused for an organization whose billing is settled by its agreement with Mountaya (403).
  • The organization must already have a billing account, which creating the organization opens, or postOrganizationBillingProvision when it comes first. One that does not answers 409, and nothing is written.
  • A tax identifier the payment provider refuses is a 400 at tax_id.value, or at tax_id.type when the type is at fault, and nothing is changed: the previous tax identifier is replaced only once the new one is accepted.
  • An address that would leave the organization's running Data API subscription without a location its tax can be computed from (the address cleared, its country removed, or one the payment provider cannot place) is a 400 at address, and the name, email and address are left as they were.
  • It is refused with 503 while another billing change for the organization is running, and nothing is written.
  • Changing the organization's own name through patchOrganization never changes the name invoices are addressed to. That name stays the organization's name as it was when billing was opened until it is changed here.

Webhook events organization.billing.info.updated, recorded by the task organization.billing.info.update.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Body

The fields to write. Every one is optional; a field that is present replaces what was there, and one that is absent leaves it alone.

name

string

in body

The name to address invoices to. Present and empty restores the organization's own name, which is why no minimum is declared: any OTHER value is at least two characters, and the empty string is the one way to ask for the default back. A minimum here would take that away from every generated client.

email

string (email)

in body

The address to send invoices and payment notices to. Optional and not nullable: omit it to keep the current address.

address

object

in body

The billing address to write. Optional and not nullable: omit it to keep the address on file; an object whose fields are all empty clears it.

tax_id

object

in body

The tax identifier to register. Optional and not nullable: omit it to keep the one on file; a value of the empty string clears it.

Response 200

The billing information after the change, in full.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

BillingInfo

required

The billing information held for an organization: the name and email an invoice is addressed to, the billing address, and the tax identifier when one is registered. The address is absent when none is on file, and so is the tax identifier.

See the BillingInfo object.

Errors 400, 401, 403, 404, 409, 413, 429, 500, 503, 504. See Errors.

curl -s -X PATCH https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/info \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "line1": "190 place de l'"'"'Église",
      "city": "Chamonix-Mont-Blanc",
      "postal_code": "74400",
      "country": "FR"
    },
    "tax_id": {"type": "eu_vat", "value": "FR40303265045"}
  }'
200
Response
{
  "data": {
    "name": "Compagnie des Guides",
    "email": "billing@example.com",
    "address": {
      "line1": "190 place de l'Église",
      "city": "Chamonix-Mont-Blanc",
      "postal_code": "74400",
      "country": "FR"
    },
    "tax_id": {
      "type": "eu_vat",
      "value": "FR40303265045"
    }
  }
}

List an organization's invoices

GET
/v1/organizations/{organization_id}/billing/invoices

Returns the organization's invoices, most recent first, each with its number, date, total, what is still owed, and the links a payer follows to view or download it. Amounts are in the currency's minor unit and are reported as the payment provider holds them: nothing here is recomputed.

  • A session token minted for api without a user is what authorizes this read, and no member role is checked on top of it; one minted for studio-embedded without a user is the 401 a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. The path names the key's own organization: another is a 403, whether or not it exists.
  • The organization must already have a billing account, which creating the organization opens, or postOrganizationBillingProvision when it comes first. One that does not answers 404.
  • For a self-serve organization, the history is empty until its first card opens its Data API subscription. From then it grows by one invoice for each billing period the subscription is in force, a period running from the day of the month it opened to the same day of the next, each billing the Data API requests of the period that has just closed, and by the closing invoice of a subscription that ends. It never shrinks.
  • For an organization billed by its agreement with Mountaya, or awaiting one, the history holds the invoices issued to it and never a draft, so status=draft lists none for it. Its invoices carry no hosted_invoice_url: it settles them as its agreement says, never through the payment provider's page, and downloads each one as a PDF.
  • A void invoice is never listed: it was withdrawn and nobody owes it, so status=void lists none.
  • status keeps the invoices that stand at it, so status=open lists what is still to be paid.
  • The listing is paged, 50 invoices to a page unless limit says otherwise, the most recent first, as the payment provider returns them; the order is not the caller's to choose, so the listing takes no sort. Send the page's next_cursor back as cursor for the next one; the last page reports next_cursor: null.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Query parameters

cursor

string

in query

Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.

limit

integer (int32)

in query

default: 50

How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.

status

string

in query

One of: draft, open, paid, void, uncollectible

Keep only the invoices that stand at this status.

Response 200

One page of the organization's invoices, most recent first. extensions.metadata.pagination.next_cursor asks for the next page, and is null on the last.

extensions

object

required

The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at, and the next_cursor of the page after it, null on the last.

data

array of Invoice

required

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

curl -s https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/invoices \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": [
    {
      "id": "in_1QeChamonix",
      "number": "MTYA-0042",
      "created_at": "2026-08-01T02:14:07Z",
      "total": 5700,
      "amount_due": 0,
      "currency": "eur",
      "status": "paid",
      "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1Qe/test_YWNjdF8xUWU",
      "invoice_pdf": "https://invoice.stripe.com/i/acct_1Qe/test_YWNjdF8xUWU/pdf"
    }
  ],
  "extensions": {
    "metadata": {
      "pagination": {
        "limit": 50,
        "next_cursor": "eyJ2IjoxLCJzIjoiLXVwZGF0ZWRfYXQifQ"
      }
    }
  }
}

List an organization's saved payment methods

GET
/v1/organizations/{organization_id}/billing/payment-methods

Returns the payment methods saved against the organization, each marked with whether it is the one invoices and subscriptions charge. Only display detail is carried: a card's brand, last four digits and expiry, or a mandate's last four and country. No card number and no IBAN passes through this contract.

  • A session token minted for api without a user is what authorizes this read, and no member role is checked on top of it; one minted for studio-embedded without a user is the 401 a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. The path names the key's own organization: another is a 403, whether or not it exists.
  • The organization must already have a billing account, which creating the organization opens, or postOrganizationBillingProvision when it comes first. One that does not answers 404.
  • The listing is paged, 50 methods to a page unless limit says otherwise, the most recently saved first; the order is not the caller's to choose, so the listing takes no sort. Send the page's next_cursor back as cursor for the next one; the last page reports next_cursor: null.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Query parameters

cursor

string

in query

Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.

limit

integer (int32)

in query

default: 50

How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.

Response 200

One page of the payment methods saved against the organization, the most recently saved first. extensions.metadata.pagination.next_cursor asks for the next page, and is null on the last.

extensions

object

required

The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at, and the next_cursor of the page after it, null on the last.

data

array of PaymentMethod

required

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

curl -s https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/payment-methods \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": [
    {
      "id": "pm_1QeChamonix",
      "type": "card",
      "is_default": true,
      "card": {
        "brand": "visa",
        "last4": "4242",
        "exp_month": 11,
        "exp_year": 2029
      }
    }
  ],
  "extensions": {
    "metadata": {
      "pagination": {
        "limit": 50,
        "next_cursor": "eyJ2IjoxLCJzIjoiLXVwZGF0ZWRfYXQifQ"
      }
    }
  }
}

Save a confirmed card against an organization

POST
/v1/organizations/{organization_id}/billing/payment-methods

Completes the card collection started by postOrganizationBillingPaymentMethodSetup, and returns the payment method saved. The confirmed setup intent is checked, the metered Data API subscription is opened on its card where the organization holds none, or only one that has ended, and the card then becomes the organization's default and the card every subscription that is charged automatically and has not ended charges: one already charging another card moves onto it, and every invoice such a subscription still has outstanding is charged to it. A subscription billed by invoice is left as it is. When no billing address is on file and the card carries one, the card's address becomes the billing address, which is what lets tax be computed on the organization's invoices. Read getOrganizationBillingSubscription for the subscription the card opened or moved.

  • The answer is 201, with Location naming the payment method, when this request attached it to the organization, and 200 with the same payment method when it was already the organization's default card, by an earlier call or by the steps that run on their own once the setup succeeds. A card still confirming is not the default yet, so a repeat for it answers 201 again. A client treats both as the card being saved.
  • The first card is what opens the Data API subscription, the one product an organization obtains by card. Where the organization has never held one, or the one it held has ended, one is opened on the card, and from then the organization holds data, which a key carrying data or mcp needs. It is metered: nothing is charged as it opens, and the requests the organization made are invoiced with tax at the end of each billing period, a month counted from the day it opened. The promotion code recorded by postOrganizationBillingProvision is applied to the organization's first subscription and to no later one. Where a subscription has not ended, none is opened, and its outstanding invoices are what the card is charged.
  • Map Studio, Map Publishing, the Tile API, Embedded Studio and White label are granted by the organization's agreement with Mountaya. No card opens any of them, and saving one changes none of them.
  • Where a subscription has not ended, a charge of its outstanding invoices the card's issuer refuses does not undo the save: the answer is still a success, the card stays the default, and the invoice it was for stays open. An issuer that answers by asking the cardholder to authenticate refuses in the same way, since the charge is made without the cardholder present: the card is saved, and another card, or the cardholder paying the invoice, is the remedy.
  • The subscription's invoices are taxed. When the payment provider cannot tell where the organization is taxed, which is the case when no billing address is on file and the card carries none, the answer is a 400 naming setup_intent_id, the intent whose card has no address to be taxed at; its message is what asks for a billing address. The card is saved but is not made the default, and nothing is opened or charged. Set a billing address with patchOrganizationBillingInfo and call this again with the same setup intent: the repeat opens the subscription.
  • When the promotion code recorded for the organization is refused by the payment provider as it is redeemed, the answer is a 400 whose entry names no field, since the code is no part of this request. Nothing is opened or charged, and the card is saved but is not made the default. Call postOrganizationBillingProvision again with another code, or with none, then call this again with the same setup intent.
  • Before a subscription is opened, every invoice the organization still owes, open or uncollectible, those of a subscription that has ended included, is collected on the card being saved. When one cannot be collected on it, the answer is a 402: nothing is opened, and the card is saved but is not made the default. The organization does not start a new subscription while it owes for an earlier one: pay what is owed, or save a card that can pay it, and call this again.
  • Nor is a subscription opened on a card another organization still owes on. A card is recognized by its number, whichever organization saved it, and while any other organization owes an invoice that a payment on a card of the same number failed to pay, one marked uncollectible or one still open after that attempt, the answer is the same 402: nothing is opened, nothing the other organization owes is charged here, and the card is saved but is not made the default. Only what the card itself failed to pay refuses it: a card the other organization merely has on file, or used to pay something else, blocks nothing, and neither does an invoice whose payment is still processing. What that organization owes is settled on it, and this is called again once it is.
  • The subscription is opened on the card being saved. Nothing is charged as it opens, unless the organization already owes an amount outside any subscription, which its first invoice collects on that card at once. When the card is refused as the subscription opens, the answer is a 400 naming setup_intent_id: nothing is opened, and the card is saved but is not made the default. Another card opens the subscription.
  • Confirming the setup intent in the browser is enough on its own: once the payment provider reports it succeeded, the same steps run shortly after, whether or not this operation is called, the Data API subscription opened where they open one. For a card, calling it runs them before it answers, so the card is on file for the very next request. Calling it is also how either 400 above is learned of: when the steps run without this call, the card is saved without becoming the default and no answer says why.
  • Owner or admin only (403 otherwise), and refused for an organization whose billing is settled by its agreement with Mountaya (403).
  • A setup intent that is unknown, or that belongs to another organization, is a 404, and nothing is saved. One of another organization is answered as an unknown one is, so a setup intent cannot be probed here.
  • A setup intent of this organization that has not been confirmed, that waits on the cardholder, that failed or was canceled, or that carries no payment method, is a 409 naming setup_intent_id, and nothing is saved. Complete the confirmation in the browser, or start again with postOrganizationBillingPaymentMethodSetup; sending the same intent again is answered the same way until it succeeds.
  • The organization must already have a billing account, which creating the organization opens, or postOrganizationBillingProvision when it comes first. One that does not answers 409.
  • A method that settles slowly, such as a SEPA Direct Debit mandate, is accepted while it is still confirming: it is saved and returned with is_default false, and the subscription is left as it was. It becomes the default once it confirms, so read is_default rather than assuming the method is live on the answer.
  • Calling it twice with the same setup intent answers the same payment method (200 once it is the default card), and changes nothing the second time unless the first was answered the 400 for a billing address or the one for a promotion code, either of which the repeat looks at afresh once its cause is put right. A refused card is refused again.

Webhook events organization.billing.payment_method.attached, organization.billing.payment_method.updated, organization.billing.info.updated, organization.billing.subscription.created, recorded by the task organization.billing.payment_method.attach.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Body

The setup intent to save the card from, as confirmed in the browser.

setup_intent_id

string

in body

required

Identifier of the confirmed setup intent, as returned by postOrganizationBillingPaymentMethodSetup and confirmed by Stripe Elements: seti_ and at most 250 more letters, digits and underscores.

Response 200

The payment method was already the organization's default card, made so by an earlier call with the same setup intent or by the steps that run once the setup succeeds: data is that method, as getOrganizationBillingPaymentMethods lists it. Nothing was saved a second time.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

PaymentMethod

required

A payment method saved against the organization's billing account. type says which instrument it is and which sub-object is present: card carries card, and sepa_debit carries sepa_debit. is_default marks the one invoices and subscriptions charge; at most one saved method carries it, and none does until a default has been chosen.

See the PaymentMethod object.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 503, 504. See Errors.

curl -s -X POST https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/payment-methods \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"setup_intent_id": "seti_1QeChamonix"}'
200
Response
{
  "data": {
    "id": "pm_1QeChamonix",
    "type": "card",
    "is_default": true,
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 11,
      "exp_year": 2029
    }
  }
}

Start collecting a card for an organization

POST
/v1/organizations/{organization_id}/billing/payment-methods/setup

Returns a single-use secret for collecting a card inside the caller's own page rather than sending the payer somewhere else. Hand it to Stripe Elements, which confirms the card in the browser, then name the confirmed setup intent on postOrganizationBillingPaymentMethod to save the card against the organization. Each call starts a collection of its own with a secret of its own. Nothing is saved by this operation on its own: a secret that is never confirmed leaves the organization exactly as it was. One that is confirmed is saved even if that call never comes: once the payment provider reports the setup succeeded, the steps postOrganizationBillingPaymentMethod describes run shortly after. Where the organization holds no Data API subscription, or only one that has ended, the card opens one, metered and invoiced by the month for what is used, then becomes the default.

  • Owner or admin only (403 otherwise), and refused for an organization whose billing is settled by its agreement with Mountaya (403).
  • The organization must already have a billing account, which creating the organization opens, or postOrganizationBillingProvision when it comes first. One that does not answers 409.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Response 200

The secret to confirm the card with, single-use and belonging to this organization alone.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

SetupIntentSession

required

A single-use secret for collecting a card in the caller's own page rather than sending the payer elsewhere. Hand client_secret to Stripe Elements, which confirms the card in the browser, then name the confirmed setup intent on postOrganizationBillingPaymentMethod to save the card against the organization.

Errors 400, 401, 403, 404, 409, 429, 500, 504. See Errors.

curl -s -X POST https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/payment-methods/setup \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq -r '.data.client_secret'
200
Response
{
  "data": {
    "client_secret": "seti_1QeChamonix_secret_MtYaExampleSecret"
  }
}

Detach a payment method from an organization

DELETE
/v1/organizations/{organization_id}/billing/payment-methods/{payment_method_id}

Removes a saved payment method from the organization.

  • Owner or admin only (403 otherwise), and refused for an organization whose billing is settled by its agreement with Mountaya (403).
  • The method must belong to this organization: an identifier naming none of its methods is a 404, whether it names another organization's method or nothing at all, and the two answer alike. A method already detached names none of them, so a second detach is that 404 too; send a retried detach with the same Idempotency-Key and it is answered with the first one's 200.
  • Detaching the default while another method is saved is a 409: make another one the default with postOrganizationBillingPaymentMethodSetDefault first. Detaching the default when it is the only method leaves the organization without one: while its Data API subscription is in force, a key's Data API request then answers 402 until another is saved.
  • The organization must already have a billing account, which creating the organization opens, or postOrganizationBillingProvision when it comes first. One that does not answers 404.

Webhook events organization.billing.payment_method.detached, recorded by the task organization.billing.payment_method.detach.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

payment_method_id

string

in path

required

Identifier of the payment method the operation acts on, as returned by getOrganizationBillingPaymentMethods. It is an opaque pm_ identifier rather than a UUID, which is why it carries a pattern instead of a format; a value that does not match the pattern is a 400 before the organization is consulted.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Response 200

The method is detached. data is null; read getOrganizationBillingPaymentMethods to see what is left.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

any | null

required

Always null: this operation answers with no payload.

Errors 400, 401, 403, 404, 409, 429, 500, 503, 504. See Errors.

curl -s -X DELETE https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/payment-methods/pm_1QeChamonix \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": null
}

Choose which payment method an organization is charged on

POST
/v1/organizations/{organization_id}/billing/payment-methods/{payment_method_id}/set-default

Makes one saved payment method the one invoices and subscriptions charge, and returns it. At most one is the default at a time, so this both sets the new one and unsets the old.

  • Owner or admin only (403 otherwise), and refused for an organization whose billing is settled by its agreement with Mountaya (403).
  • The method must belong to this organization: an identifier naming none of its methods is a 404, whether it names another organization's method or nothing at all, and the two answer alike.
  • The organization must already have a billing account, which creating the organization opens, or postOrganizationBillingProvision when it comes first. One that does not answers 404.
  • Every subscription that is charged automatically and has not ended moves onto this method, and the invoices such a subscription still has outstanding are charged to it at once. A charge the issuer refuses does not undo the choice: the answer is still 200, the method is the default, and that invoice stays open.
  • It opens no subscription. An organization with no Data API subscription in force that makes a saved method its default has a default and still no subscription: opening one takes a card saved through postOrganizationBillingPaymentMethod, or postOrganizationBillingSubscription, which opens one on the default payment method.
  • Setting the same default twice changes nothing the second time, and is answered with the method as it stands.

Webhook events organization.billing.payment_method.updated, recorded by the task organization.billing.payment_method.set_default.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

payment_method_id

string

in path

required

Identifier of the payment method the operation acts on, as returned by getOrganizationBillingPaymentMethods. It is an opaque pm_ identifier rather than a UUID, which is why it carries a pattern instead of a format; a value that does not match the pattern is a 400 before the organization is consulted.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Response 200

The method is the one that gets charged from here on: data is the method, as getOrganizationBillingPaymentMethods lists it, with is_default true. The previous default stays saved with is_default false.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

PaymentMethod

required

A payment method saved against the organization's billing account. type says which instrument it is and which sub-object is present: card carries card, and sepa_debit carries sepa_debit. is_default marks the one invoices and subscriptions charge; at most one saved method carries it, and none does until a default has been chosen.

See the PaymentMethod object.

Errors 400, 401, 403, 404, 409, 429, 500, 503, 504. See Errors.

curl -s -X POST https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/payment-methods/pm_1QeChamonix/set-default \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": {
    "id": "pm_1QeChamonix",
    "type": "card",
    "is_default": true,
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 11,
      "exp_year": 2029
    }
  }
}

Check what a promotion code is worth to an organization

GET
/v1/organizations/{organization_id}/billing/promotion-codes/{code}

Checks a promotion code against this organization and returns what it would be worth, so a client can show the discount before the code is given to postOrganizationBillingProvision, which records it for the organization's first Data API subscription.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

code

string

in path

required

The promotion code to check, as it was handed to the customer: 1 to 64 letters, digits, hyphens and underscores. A value of any other shape is a 400 naming code, and is never looked up.

Response 200

What the code is worth to this organization, or valid: false when it cannot be used here.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

PromotionCodePreview

required

What a promotion code would be worth to this organization, so a client can show the discount before the code is given to provisioning, rather than finding out once the first card opens the subscription it discounts.

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

curl -s https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/billing/promotion-codes/EARLYGUIDE \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": {
    "valid": true,
    "label": "Early guide, 20% off",
    "percent_off": 20,
    "duration": "repeating"
  }
}