Assign a plan to a customer
Route
POST
/api/v1/subscriptions
Usage
- Curl
- Python
- Javascript
- Ruby
- Go
- C#
- PHP
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.client import Client
from lago_python_client.exceptions import LagoApiError
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"
)
try:
client.subscriptions.create(subscription)
except LagoApiError as e:
repair_broken_state(e) # do something on error or raise your own exception
import { Client, SubscriptionObject } from "lago-javascript-client";
const subscriptionObject = {
externalCustomerId: "5eb02857-a71e-4ea2-bcf9-57d8885990ba",
planCode: "code",
externalId: "id",
name: "display name",
subscriptionAt: "2022-08-08T00:00:00Z",
billingTime: "anniversary" as SubscriptionObject["billingTime"],
};
await client.subscriptions.createSubscription({
subscription: subscriptionObject,
});
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)
}
using System.Collections.Generic;
using System.Diagnostics;
using Org.OpenAPITools.Api;
using Org.OpenAPITools.Client;
using Org.OpenAPITools.Model;
namespace Example
{
public class CreateSubscriptionExample
{
public static void Main()
{
Configuration.Default.BasePath = "https://api.getlago.com/api/v1";
// Configure HTTP bearer authorization: bearerAuth
Configuration.Default.AccessToken = "YOUR_ACCESS_TOKEN";
var apiInstance = new SubscriptionsApi(Configuration.Default);
var subscriptionCreateInput = new SubscriptionCreateInput(); // SubscriptionCreateInput | Subscription payload
try
{
// Assign a plan to a customer
Subscription result = apiInstance.CreateSubscription(subscriptionCreateInput);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling SubscriptionsApi.CreateSubscription: " + e.Message );
Debug.Print("Status Code: "+ e.ErrorCode);
Debug.Print(e.StackTrace);
}
}
}
}
<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure Bearer authorization: bearerAuth
$config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');
$apiInstance = new OpenAPI\Client\Api\SubscriptionsApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
new GuzzleHttp\Client(),
$config
);
$subscription_create_input = new \OpenAPI\Client\Model\SubscriptionCreateInput(); // \OpenAPI\Client\Model\SubscriptionCreateInput | Subscription payload
try {
$result = $apiInstance->createSubscription($subscription_create_input);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling SubscriptionsApi->createSubscription: ', $e->getMessage(), PHP_EOL;
}
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 |