Apply an add-on to a customer

caution

This endpoint is deprecated and will be removed on September 1st, 2023. It has been replaced with the endpoint to create one-off invoices.

Route

POST

/api/v1/applied_add_ons

Usage

Curl

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

curl --location --request POST "$LAGO_URL/api/v1/applied_add_ons" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "applied_add_on": {
      "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "add_on_code": "code",
      "amount_cents": 123,
      "amount_currency": "EUR"
    }
  }'

Python

from lago_python_client.client import Client
from lago_python_client.exceptions import LagoApiError
from lago_python_client.models import AppliedAddOn

client = Client(api_key='__YOUR_API_KEY__')

applied_add_on = AppliedAddOn(
  external_customer_id="5eb02857-a71e-4ea2-bcf9-57d8885990ba",
  add_on_code="code",
  amount_cents=123,
  amount_currency="EUR"
)

try:
    client.applied_add_ons.create(applied_add_on)
except LagoApiError as e:
    repair_broken_state(e)  # do something on error or raise your own exception

Ruby

require 'lago-ruby-client'

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

client.applied_add_ons.create(
  external_customer_id: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
  add_on_code: "code",
  amount_cents: 123,
  amount_currency: "EUR"
)

Javascript

const appliedAddOnObject = {
  externalCustomerId: "5eb02857-a71e-4ea2-bcf9-57d8885990ba",
  addOnCode: "code",
  amountCents: 123,
  amountCurrency: "EUR",
};

await client.appliedAddOns.applyAddOn({
  appliedAddOn: appliedAddOnObject,
});

Go

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

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

    addOnInput := &lago.ApplyAddOnInput{
      ExternalCustomerID:     "__YOUR_CUSTOMER_ID__",
            AddOnCode:      "__YOUR_ADDON_CODE__",
            AmountCents:    1000,
            AmountCurrency: lago.EUR,
    }

    appliedAddOn, err := lagoClient.AddOn().ApplyToCustomer(addOnInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // appliedAddOn is *lago.AppliedAddOn
    fmt.Println(appliedAddOn)
  }

C#

using System.Collections.Generic;
using System.Diagnostics;
using Org.OpenAPITools.Api;
using Org.OpenAPITools.Client;
using Org.OpenAPITools.Model;

namespace Example
{
  public class ApplyAddOnExample
  {
      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 AddOnsApi(Configuration.Default);
          var appliedAddOnInput = new AppliedAddOnInput(); // AppliedAddOnInput | Apply add-on payload

          try
          {
              // Apply an add-on to a customer
              AppliedAddOn result = apiInstance.ApplyAddOn(appliedAddOnInput);
              Debug.WriteLine(result);
          }
          catch (ApiException e)
          {
              Debug.Print("Exception when calling AddOnsApi.ApplyAddOn: " + 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\AddOnsApi(
  // 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
);
$applied_add_on_input = new \OpenAPI\Client\Model\AppliedAddOnInput(); // \OpenAPI\Client\Model\AppliedAddOnInput | Apply add-on payload

try {
  $result = $apiInstance->applyAddOn($applied_add_on_input);
  print_r($result);
} catch (Exception $e) {
  echo 'Exception when calling AddOnsApi->applyAddOn: ', $e->getMessage(), PHP_EOL;
}

Arguments

{
  "applied_add_on": {
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "add_on_code": "code",
    "amount_cents": 123,
    "amount_currency": "EUR"
  }
}

Attributes	Type	Description
external_customer_id	String      Required	Customer unique identifier in your application
add_on_code	String      Required	Code identifying the add-on. It must match the code property of the add-on
amount_cents	Integer      Optional	Amount (excluding tax) to apply to the customer. If defined, it overrides the amount_cents property of the add-on
amount_currency	String      Optional	Currency of the amount to apply to the customer. If defined, it overrides the amount_currency property of the add-on. It must match the currency of the customer's plan.

Responses

HTTP 200

The add-on was assigned to the customer.

Returns an applied add-on object.

HTTP 400

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

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

HTTP 401

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

Access to the API endpoint 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.
• add_on_not_found: The add-on code does not match an existing add-on.

HTTP 422

{
  "status": 422,
  "error": "Unprocessable entity",
  "message": "message"
}

Possible errors:

field	error	description
amount_cents	value_is_out_of_range	Provided amount cents is invalid. It must be a positive integer.
amount_currency	value_is_invalid	Provided currency value is invalid

The applied add-on object

This object represents an add-on assigned to a customer of your business.

Schema

{
  "applied_add_on": {
    "lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
    "lago_add_on_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
    "add_on_code": "add-on-code",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
    "amount_cents": 123,
    "amount_currency": "EUR",
    "created_at": "2022-04-29T08:59:51Z"
  }
}

Attributes	Description
lago_id     String     Not null	Unique identifer of the applied add-on in Lago application.
lago_add_on_id     String     Not null	Unique identifer of the add-on in Lago application.
add_on_code     String     Not null	Code identifying the add-on.
external_customer_id     String     Not null	Unique identifer of the customer in your application.
lago_customer_id     String     Not null	Unique identifer of the customer in Lago application.
amount_cents     Integer     Not null	Amount in cents (excluding tax).
amount_currency     String     Not null	Currency of the amount.
created_at     String     Not null     ISO 8601 datetime in UTC	Date of assignation of the add-on to the customer.