Skip to content
Baremetrics

Create Subscription

POST https://api.baremetrics.com/v1/{source_id}/subscriptions

This endpoint allows you to create a Subscription.

You will need to create a Customer and Plan before you can use this endpoint.

[!CAUTION] It may take a while for your subscriptions to appear in your metrics. There may also be a delay in the data being fully displayed in the GET /subscriptions endpoint.

[!WARNING] How and why do I use addons?

Addons are used to add additional charges to a base plan. They allow you to create a variety of different combinations of features without creating a separate plan for each possible combination.

Let's look at a hypothetical way of charging for Baremetrics.

We could have a base subscription of $25/mo. Additional features like dunning, customer profiles, etc. could be treated as an addon.

$25/mo. base charge + $25 addon for Dunning = $50/mo.

[!NOTE] We will automatically create charges for your subscriptions. If you don't want this to happen, then please contact us.

Path parameters

  • source_id string required

    Please see Sources

Body

application/json
  • oid string required

    Your unique ID for the subscription

  • started_at string · date-time required

    A unix timestamp of when this subscription started

  • canceled_at string · date-time

    A unix timestamp of when this subscription was, or should be canceled. This cannot be changed, so only set this if you are certain you know when the subscription will end.

  • plan_oid string required

    Your unique ID for the plan

  • customer_oid string required

    Your unique ID for the customer

  • addons array of objects
    • oid string required
    • amount integer · int32 required
    • quantity integer · int32 required
  • quantity integer · int32

    Default 1

  • discount integer · int32

    Integer value (in the same currency as the plan)

Responses

200OK
{
  "event": {
    "id": "48X1ZZHtRaBtfN",
    "type": "subscription.created",
    "info": {
      "oid": "subscription_51",
      "started_at": 1474381618,
      "plan_oid": "1476719008009",
      "customer_oid": "1476719006346",
      "canceled_at": null,
      "quantity": 1,
      "addons": [
        {
          "oid": "addon_1",
          "amount": 100,
          "quantity": 1
        },
        {
          "oid": "addon_2",
          "amount": 50,
          "quantity": 1
        }
      ]
    },
    "occurred_at": 1474381618,
    "received_at": 1480421211
  }
}
400Bad Request
{
  "error": "Error message here"
}