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",
      "subscription_at": "2022-08-08T00:00:00Z",
      "billing_time": "anniversary"
    }
  }'

Python

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

Javascript

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,
});

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",
  subscription_at: "2022-08-08T00:00:00Z",
  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__",
      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)
  }

C#

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

<?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

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
subscription_at	invalid_date	Field does not have a valid ISO 8601 datetime format