Assign a plan to a customer
Route
POST
/api/v1/subscriptions
Usage
- Curl
- Python
- Node.js
- Ruby
- Go
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",
"subscription_at": "2022-08-08T00:00:00Z",
"billing_time": "anniversary"
}
}'
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",
subscription_at="2022-08-08T00:00:00Z",
billing_time="anniversary"
)
client.subscriptions().create(subscription)
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",
subscriptionAt: "2022-08-08T00:00:00Z",
billingTime: "anniversary"
})
await client.createSubscription(subscription);
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",
subscription_at: "2022-08-08T00:00:00Z",
billing_time: "anniversary"
)
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__",
SubscriptionAt: "2022-08-08T00:00:00Z",
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",
"subscription_at": "2022-08-08T00:00:00Z",
"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. |
subscription_at | String Optional ISO 8601 datetime in UTC | Can be used to create a subscription that started in the past or will start in the future. Cannot be used to update the start date of a pending subscription or to schedule an upgrade/downgrade. |
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
Deprecated arguments
Attributes | Type | Description |
---|---|---|
subscription_date | String Optional | Can be used to create a subscription that started in the past or will start in the future. Cannot be used to update the start date of a pending subscription or to schedule an upgrade/downgrade. |
Responses
- HTTP 200
- HTTP 400
- HTTP 401
- HTTP 404
- HTTP 422
The plan was succesfuly assigned to the customer. A subscription has been created.
Returns a subscription object.
{
"status": 400,
"error": "Bad Request"
}
The subscription
json root is not present in the request body.
{
"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
{
"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.
{
"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 |
subscription_at | invalid_date | Field does not have a valid ISO 8601 datetime format |