Legacy (v0)

Add an item to an autoship profile

Adds a recurring item to the autoship profile. It first bills and ships with the profile’s next order, at the price one unit renews at. The response carries the profile after the add and the new item’s subscription_token. Nothing is charged now.

When the preview’s quote.outcome is align_required, send its quote.confirmation as confirmation; without it the add refuses with confirmation_required. The add refuses with quote_changed when the profile’s date, address, card or plan, or the item’s price, changed since the preview, or when the confirmation is expired or is for other terms. Preview again and ask the customer to confirm.

Generate one request_key per add and send it again on a retry. A retry with the same request_key answers 201 with the same subscription_token and adds nothing. A request_key that added another item is refused with request_key_reused.

Requires the subscriptions update permission and an admin, and the autoship_profiles feature to work for the company. The profile is the one whose members are exactly subscription_tokens, among the subscriptions of the customer who owns {token}. An address or card must be that customer’s. The lifecycle notes credit the admin. Returns 403 naming the failed check in errors.error when the feature is off, 404 when the subscription is not the company’s or a token is not the customer’s, 409 with meta.code profile_changed when the profile’s members changed since the client read them, 422 when the change is refused (the reason is in meta.code), and 401 when unauthenticated. Responses are not cached.

POST

api

subscriptions

{token}

profile

items

Add an item to an autoship profile

curl --request POST \
  --url https://api.fluid.app/api/subscriptions/{token}/profile/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscription_tokens": [
    "sb_7Qm2VxK9pRtL4wNc8HzJdF",
    "sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn"
  ],
  "variant_id": 4821,
  "quantity": 2,
  "request_key": "6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14",
  "confirmation": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19"
}
'

import requests

url = "https://api.fluid.app/api/subscriptions/{token}/profile/items"

payload = {
    "subscription_tokens": ["sb_7Qm2VxK9pRtL4wNc8HzJdF", "sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn"],
    "variant_id": 4821,
    "quantity": 2,
    "request_key": "6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14",
    "confirmation": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subscription_tokens: ['sb_7Qm2VxK9pRtL4wNc8HzJdF', 'sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn'],
    variant_id: 4821,
    quantity: 2,
    request_key: '6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14',
    confirmation: 'eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19'
  })
};

fetch('https://api.fluid.app/api/subscriptions/{token}/profile/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fluid.app/api/subscriptions/{token}/profile/items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subscription_tokens' => [
        'sb_7Qm2VxK9pRtL4wNc8HzJdF',
        'sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn'
    ],
    'variant_id' => 4821,
    'quantity' => 2,
    'request_key' => '6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14',
    'confirmation' => 'eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fluid.app/api/subscriptions/{token}/profile/items"

	payload := strings.NewReader("{\n  \"subscription_tokens\": [\n    \"sb_7Qm2VxK9pRtL4wNc8HzJdF\",\n    \"sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn\"\n  ],\n  \"variant_id\": 4821,\n  \"quantity\": 2,\n  \"request_key\": \"6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14\",\n  \"confirmation\": \"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.fluid.app/api/subscriptions/{token}/profile/items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscription_tokens\": [\n    \"sb_7Qm2VxK9pRtL4wNc8HzJdF\",\n    \"sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn\"\n  ],\n  \"variant_id\": 4821,\n  \"quantity\": 2,\n  \"request_key\": \"6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14\",\n  \"confirmation\": \"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fluid.app/api/subscriptions/{token}/profile/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscription_tokens\": [\n    \"sb_7Qm2VxK9pRtL4wNc8HzJdF\",\n    \"sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn\"\n  ],\n  \"variant_id\": 4821,\n  \"quantity\": 2,\n  \"request_key\": \"6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14\",\n  \"confirmation\": \"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19\"\n}"

response = http.request(request)
puts response.read_body

{
  "profile": {
    "next_bill_date": "2026-10-14",
    "billing_interval": 1,
    "billing_interval_unit": "month",
    "members": [
      {
        "subscription_token": "sb_7Qm2VxK9pRtL4wNc8HzJdF",
        "label": "Dunder Mifflin 20lb Copy Paper",
        "status": "active"
      },
      {
        "subscription_token": "sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn",
        "label": "Dunder Mifflin Toner Cartridge",
        "status": "active"
      },
      {
        "subscription_token": "sb_9Xc5Bn3Qa6Zs2Ye7Df1Wk",
        "label": "Dunder Mifflin Toner Cartridge",
        "status": "active"
      }
    ]
  },
  "subscription_token": "sb_9Xc5Bn3Qa6Zs2Ye7Df1Wk",
  "meta": {
    "request_id": "0d6c3f92-8b1e-4a75-9d2c-4f7e1a5b8c30",
    "timestamp": "2026-09-30T14:05:22Z"
  }
}

{
  "message": "<string>",
  "error": "<string>",
  "error_message": "<string>",
  "errors": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "code": "<string>",
    "payment_uuid": "<string>",
    "error_details": [
      {
        "code": "<string>",
        "field": "<string>",
        "payment": "not_attempted",
        "message": "<string>"
      }
    ],
    "coded_recovery": true
  }
}

{
  "message": "<string>",
  "error": "<string>",
  "error_message": "<string>",
  "errors": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "code": "<string>",
    "payment_uuid": "<string>",
    "error_details": [
      {
        "code": "<string>",
        "field": "<string>",
        "payment": "not_attempted",
        "message": "<string>"
      }
    ],
    "coded_recovery": true
  }
}

{
  "error_message": "<string>",
  "errors": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "code": "<string>"
  }
}

{
  "error_message": "<string>",
  "errors": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "code": "<string>"
  }
}

{
  "error_message": "<string>",
  "errors": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "code": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Bearer token authentication

Path Parameters

token

string

required

A subscription of the customer whose profile changes.

Body

application/json

subscription_tokens

string[]

required

The member tokens of the profile, as the client last read them.

Minimum array length: 2

variant_id

integer

required

The variant to add. It must belong to the company.

quantity

integer

required

How many units each renewal ships.

Required range: x >= 1

request_key

string

required

Identifies this add. The client generates one per add and sends it again on a retry.

Required string length: 1 - 255

confirmation

string

The quote.confirmation from the preview of these terms. Required when the preview's outcome is align_required.

Response

The item was added, or an earlier request with the same request_key already added it.

The autoship profile after an item joined it, and the new item's token. profile is null only when the profile cannot be derived after the add.

profile

object | null

required

The autoship profile this subscription belongs to: the subscriptions that renew as one order and also share a payment method, a plan cadence and a timezone, so they stay together after each shipment. Derived from the subscriptions on every read and never stored.

Show child attributes

subscription_token

string

required

The token of the subscription the add created, or created on the first request with the same request_key.

meta

object | null

required

Show child attributes

Add an item to an autoship profile

curl --request POST \
  --url https://api.fluid.app/api/subscriptions/{token}/profile/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscription_tokens": [
    "sb_7Qm2VxK9pRtL4wNc8HzJdF",
    "sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn"
  ],
  "variant_id": 4821,
  "quantity": 2,
  "request_key": "6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14",
  "confirmation": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19"
}
'

import requests

url = "https://api.fluid.app/api/subscriptions/{token}/profile/items"

payload = {
    "subscription_tokens": ["sb_7Qm2VxK9pRtL4wNc8HzJdF", "sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn"],
    "variant_id": 4821,
    "quantity": 2,
    "request_key": "6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14",
    "confirmation": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subscription_tokens: ['sb_7Qm2VxK9pRtL4wNc8HzJdF', 'sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn'],
    variant_id: 4821,
    quantity: 2,
    request_key: '6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14',
    confirmation: 'eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19'
  })
};

fetch('https://api.fluid.app/api/subscriptions/{token}/profile/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fluid.app/api/subscriptions/{token}/profile/items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subscription_tokens' => [
        'sb_7Qm2VxK9pRtL4wNc8HzJdF',
        'sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn'
    ],
    'variant_id' => 4821,
    'quantity' => 2,
    'request_key' => '6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14',
    'confirmation' => 'eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fluid.app/api/subscriptions/{token}/profile/items"

	payload := strings.NewReader("{\n  \"subscription_tokens\": [\n    \"sb_7Qm2VxK9pRtL4wNc8HzJdF\",\n    \"sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn\"\n  ],\n  \"variant_id\": 4821,\n  \"quantity\": 2,\n  \"request_key\": \"6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14\",\n  \"confirmation\": \"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.fluid.app/api/subscriptions/{token}/profile/items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscription_tokens\": [\n    \"sb_7Qm2VxK9pRtL4wNc8HzJdF\",\n    \"sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn\"\n  ],\n  \"variant_id\": 4821,\n  \"quantity\": 2,\n  \"request_key\": \"6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14\",\n  \"confirmation\": \"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fluid.app/api/subscriptions/{token}/profile/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscription_tokens\": [\n    \"sb_7Qm2VxK9pRtL4wNc8HzJdF\",\n    \"sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn\"\n  ],\n  \"variant_id\": 4821,\n  \"quantity\": 2,\n  \"request_key\": \"6f0d1c52-3b7e-4c1a-9a55-2e8f7d3b9c14\",\n  \"confirmation\": \"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9KYzNWaWFtVmpkQ0lMY0hKbGRtbGxkdz09In19\"\n}"

response = http.request(request)
puts response.read_body

{
  "profile": {
    "next_bill_date": "2026-10-14",
    "billing_interval": 1,
    "billing_interval_unit": "month",
    "members": [
      {
        "subscription_token": "sb_7Qm2VxK9pRtL4wNc8HzJdF",
        "label": "Dunder Mifflin 20lb Copy Paper",
        "status": "active"
      },
      {
        "subscription_token": "sb_4Mw9Tc2Kd7Rx5Hb8Lq3Pn",
        "label": "Dunder Mifflin Toner Cartridge",
        "status": "active"
      },
      {
        "subscription_token": "sb_9Xc5Bn3Qa6Zs2Ye7Df1Wk",
        "label": "Dunder Mifflin Toner Cartridge",
        "status": "active"
      }
    ]
  },
  "subscription_token": "sb_9Xc5Bn3Qa6Zs2Ye7Df1Wk",
  "meta": {
    "request_id": "0d6c3f92-8b1e-4a75-9d2c-4f7e1a5b8c30",
    "timestamp": "2026-09-30T14:05:22Z"
  }
}

{
  "message": "<string>",
  "error": "<string>",
  "error_message": "<string>",
  "errors": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "code": "<string>",
    "payment_uuid": "<string>",
    "error_details": [
      {
        "code": "<string>",
        "field": "<string>",
        "payment": "not_attempted",
        "message": "<string>"
      }
    ],
    "coded_recovery": true
  }
}

{
  "message": "<string>",
  "error": "<string>",
  "error_message": "<string>",
  "errors": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "code": "<string>",
    "payment_uuid": "<string>",
    "error_details": [
      {
        "code": "<string>",
        "field": "<string>",
        "payment": "not_attempted",
        "message": "<string>"
      }
    ],
    "coded_recovery": true
  }
}

{
  "error_message": "<string>",
  "errors": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "code": "<string>"
  }
}

{
  "error_message": "<string>",
  "errors": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "code": "<string>"
  }
}

{
  "error_message": "<string>",
  "errors": "<string>",
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "code": "<string>"
  }
}

Overview

Storefront

Commerce

Checkout

Member API

Messaging

People

Payments

DAM

Website

Portal

Mobile app

Content and tools

Analytics

Sales channels

Settings

FairShare SDK

Droplets

Developers

Unsorted endpoints

Portal & Widgets

Add an item to an autoship profile

Authorizations

Path Parameters

Body

Response