Assign a plan to a customer

Route

POST

/api/v1/subscriptions

Usage

Curl

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "subscription": {
      "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "plan_code": "code",
      "external_id": "id",
      "name": "display name",
      "billing_time": "anniversary"
    }
  }'

Python

from lago_python_client import Client
from lago_python_client.models import Subscription

client = Client(api_key='__YOUR_API_KEY__')

subscription = Subscription(
  external_customer_id="5eb02857-a71e-4ea2-bcf9-57d8885990ba",
  plan_code="code",
  external_id="id",
  name="display name",
  billing_time="anniversary"
)

client.subscriptions().create(subscription)

Node.js

import Client from 'lago-nodejs-client'
import Subscription from 'lago-nodejs-client/subscription'

let client = new Client('__API_KEY__')

let subscription = new Subscription({
  externalCustomerId: "5eb02857-a71e-4ea2-bcf9-57d8885990ba",
  planCode: "code",
  externalId: "id",
  name: "display name",
  billingTime: "anniversary"
})

await client.createSubscription(subscription);

Ruby

require 'lago-ruby-client'

client = Lago::Api::Client.new({api_key: '__YOUR_API_KEY__'})

client.subscriptions.create(
  external_customer_id: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
  plan_code: "code",
  external_id: "id",
  name: "display name",
  billing_time: "anniversary"
)

Go

  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

    subscriptionInput := &lago.SubscriptionInput{
      ExternalCustomerID:   "__YOUR_CUSTOMER_ID__",
      PlanCode:     "__YOUR_PLAN_CODE__",
      BillingTime: lago.Anniversary,
    }

    subscription, err := lagoClient.Subscription().Create(subscriptionInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // subscription is *lago.Subscription
    fmt.Println(subscription)
  }

Arguments

{
  "subscription": {
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "plan_code": "new_code",
    "name": "name",
    "external_id": "sub id",
    "billing_time": "anniversary"
  }
}

Attributes	Type	Description
external_customer_id	String      Required	Customer unique identifier in your application
plan_code	String      Required	Code identifying the plan. It must match the code property of one of the plans.
external_id	String      Required	Unique external identifier of the subscription. Used as an idempotency key.
name	String      Optional	Subscription display name.
billing_time	String      Optional	Billing time of the subscription. It can be anniversary or calendar If not provided, it will default to calendar

info

If the customer is not found, it will be created with blank metadata

Responses

HTTP 200

The plan was succesfuly assigned to the customer. A subscription has been created.

Returns a subscription object.

HTTP 400

{
  "status": 400,
  "error": "Bad Request"
}

The subscription json root is not present in the request body.

HTTP 401

{
  "status": 401,
  "error": "Unauthorized"
}

Access to the API end point is unhautorized.

Possible reasons are:

• The Authorization header is missing
• The Authorization header does not contain the API key
• The Api key is invalid or expired

HTTP 404

{
  "status": 404,
  "error": "Not Found",
  "code": "customer_not_found"
}

Possible error codes:

• customer_not_found: The external customer id does not match an existing customer.
• plan_not_found: The plan code does not match an existing plan.

HTTP 422

{
  "status": 422,
  "error": "Unprocessable entity",
  "code": "validation_errors",
  "error_details": {
    "field": ["error"]
  }
}

Possible errors:

Field	Code	Description
billing_time	value_is_invalid	Provided billing_time does not match an accepted value
currency	currencies_does_not_match	The plan currency differs from the customer currency
external_id	value_already_exists	The external id is already assigned to an active subscription
external_id	value_is_mandatory	No external id was provided in the request payload