subscriptions

Email customers whose charge failed

Tell a set of customers that the charge on their subscription failed, for the Subscription Billing day drawer.

The dunning pipeline sends its own first-decline mail once per failure streak and records that on the subscription rather than here. This endpoint does not replace it: a customer the pipeline has already written to is skipped as already_noticed, which is the only way an operator can see that it got there first. What remains are the customers it deliberately left alone.

Every token is answered. A token is sent when the mail was queued and recorded, skipped when the customer must not be mailed — with the reason — or failed when no subscription of that token belongs to the caller.

A subscription with no failed charge on renewal_date is skipped rather than mailed, so a customer whose charge cleared cannot be told it failed.

Set resend to true to tell the customers who have already been told anyway. It waives the already_noticed and already_emailed skips and nothing else, and it defaults to false, so an operator reaches those customers only by asking for them.

A send whose mail could not be queued is skipped as delivery_failed and leaves no record behind, so the same customer can be tried again immediately rather than waiting out the quiet period on a mail that never went.

POST

api

subscriptions

payment_failed_emails

Email customers whose charge failed

curl --request POST \
  --url https://api.fluid.app/api/subscriptions/payment_failed_emails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tokens": [
    "sb_primex_active_001"
  ],
  "renewal_date": "2023-12-25",
  "resend": false
}
'

import requests

url = "https://api.fluid.app/api/subscriptions/payment_failed_emails"

payload = {
    "tokens": ["sb_primex_active_001"],
    "renewal_date": "2023-12-25",
    "resend": False
}
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({tokens: ['sb_primex_active_001'], renewal_date: '2023-12-25', resend: false})
};

fetch('https://api.fluid.app/api/subscriptions/payment_failed_emails', 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/payment_failed_emails",
  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([
    'tokens' => [
        'sb_primex_active_001'
    ],
    'renewal_date' => '2023-12-25',
    'resend' => false
  ]),
  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/payment_failed_emails"

	payload := strings.NewReader("{\n  \"tokens\": [\n    \"sb_primex_active_001\"\n  ],\n  \"renewal_date\": \"2023-12-25\",\n  \"resend\": false\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/payment_failed_emails")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tokens\": [\n    \"sb_primex_active_001\"\n  ],\n  \"renewal_date\": \"2023-12-25\",\n  \"resend\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fluid.app/api/subscriptions/payment_failed_emails")

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  \"tokens\": [\n    \"sb_primex_active_001\"\n  ],\n  \"renewal_date\": \"2023-12-25\",\n  \"resend\": false\n}"

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

{
  "sent_tokens": [
    "<string>"
  ],
  "skipped_tokens": [
    {
      "token": "<string>",
      "reason": "already_emailed",
      "error": "<string>"
    }
  ],
  "failed_tokens": [
    {
      "token": "<string>",
      "error": "<string>"
    }
  ],
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

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

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

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

Authorizations

Authorization

string

header

required

Bearer token authentication

Body

application/json

Who to tell, and which day's failure the mail is about.

tokens

string[]

required

Subscription tokens. Duplicates are collapsed before the batch runs, and the deduplicated count is what the maximum is applied to.

Required array length: 1 - 500 elements

Example:

["sb_primex_active_001"]

renewal_date

string<date>

required

The renewal date being worked, as YYYY-MM-DD. A subscription with no failed charge on this date is skipped, so the caller cannot tell a customer about a failure they did not have.

resend

boolean

default:false

Whether to tell customers who have already been told, either by the dunning pipeline or by an earlier operator batch. Defaults to false, so a caller that omits it cannot mail anyone twice.

When true, only the already_noticed and already_emailed skips are waived. Every other skip still applies: a subscription with no failed charge on the date, a customer with no address, and a company with the mail switched off are passed over either way.

Example:

false

Response

Every token answered as sent, skipped, or failed

One entry per token sent, across three lists.

sent_tokens

string[]

required

Customers whose mail was queued and recorded.

skipped_tokens

object[]

required

Customers passed over, each carrying why.

Show child attributes

failed_tokens

object[]

required

Tokens that resolved to no subscription of the caller's.

Show child attributes

meta

object | null

required

Show child attributes

Email customers whose charge failed

curl --request POST \
  --url https://api.fluid.app/api/subscriptions/payment_failed_emails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tokens": [
    "sb_primex_active_001"
  ],
  "renewal_date": "2023-12-25",
  "resend": false
}
'

import requests

url = "https://api.fluid.app/api/subscriptions/payment_failed_emails"

payload = {
    "tokens": ["sb_primex_active_001"],
    "renewal_date": "2023-12-25",
    "resend": False
}
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({tokens: ['sb_primex_active_001'], renewal_date: '2023-12-25', resend: false})
};

fetch('https://api.fluid.app/api/subscriptions/payment_failed_emails', 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/payment_failed_emails",
  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([
    'tokens' => [
        'sb_primex_active_001'
    ],
    'renewal_date' => '2023-12-25',
    'resend' => false
  ]),
  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/payment_failed_emails"

	payload := strings.NewReader("{\n  \"tokens\": [\n    \"sb_primex_active_001\"\n  ],\n  \"renewal_date\": \"2023-12-25\",\n  \"resend\": false\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/payment_failed_emails")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tokens\": [\n    \"sb_primex_active_001\"\n  ],\n  \"renewal_date\": \"2023-12-25\",\n  \"resend\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fluid.app/api/subscriptions/payment_failed_emails")

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  \"tokens\": [\n    \"sb_primex_active_001\"\n  ],\n  \"renewal_date\": \"2023-12-25\",\n  \"resend\": false\n}"

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

{
  "sent_tokens": [
    "<string>"
  ],
  "skipped_tokens": [
    {
      "token": "<string>",
      "reason": "already_emailed",
      "error": "<string>"
    }
  ],
  "failed_tokens": [
    {
      "token": "<string>",
      "error": "<string>"
    }
  ],
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

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

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

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

Overview

Task guides

Portal & Widgets

Endpoints

Auth endpoints

Checkout endpoints

Public SDK endpoints

Member endpoints

Payment gateway endpoints

Cart payment endpoints

Commerce endpoints

Webhooks endpoints

Company admin endpoints (v0)

Analytics

Email customers whose charge failed

Authorizations

Body

Response