Create a mandate

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/mandates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "asset": "usdc",
  "policy": {
    "maxPerAuthorization": "50.00",
    "maxPerPeriod": {
      "amount": "500.00",
      "period": "month"
    }
  },
  "expiresAt": "2027-06-15T12:00:00.000Z",
  "approvalRedirect": {
    "failureUrl": "https://merchant.example.com/mandate/approval/failed",
    "successUrl": "https://merchant.example.com/mandate/approval/success"
  },
  "revocationRedirect": {
    "failureUrl": "https://merchant.example.com/mandate/revocation/failed",
    "successUrl": "https://merchant.example.com/mandate/revocation/success"
  },
  "customerDisplay": {
    "merchantName": "Acme Store"
  }
}
'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/mandates"

payload = {
    "asset": "usdc",
    "policy": {
        "maxPerAuthorization": "50.00",
        "maxPerPeriod": {
            "amount": "500.00",
            "period": "month"
        }
    },
    "expiresAt": "2027-06-15T12:00:00.000Z",
    "approvalRedirect": {
        "failureUrl": "https://merchant.example.com/mandate/approval/failed",
        "successUrl": "https://merchant.example.com/mandate/approval/success"
    },
    "revocationRedirect": {
        "failureUrl": "https://merchant.example.com/mandate/revocation/failed",
        "successUrl": "https://merchant.example.com/mandate/revocation/success"
    },
    "customerDisplay": { "merchantName": "Acme Store" }
}
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({
    asset: 'usdc',
    policy: {
      maxPerAuthorization: '50.00',
      maxPerPeriod: {amount: '500.00', period: 'month'}
    },
    expiresAt: '2027-06-15T12:00:00.000Z',
    approvalRedirect: {
      failureUrl: 'https://merchant.example.com/mandate/approval/failed',
      successUrl: 'https://merchant.example.com/mandate/approval/success'
    },
    revocationRedirect: {
      failureUrl: 'https://merchant.example.com/mandate/revocation/failed',
      successUrl: 'https://merchant.example.com/mandate/revocation/success'
    },
    customerDisplay: {merchantName: 'Acme Store'}
  })
};

fetch('https://api.cdp.coinbase.com/platform/v2/mandates', 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.cdp.coinbase.com/platform/v2/mandates",
  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([
    'asset' => 'usdc',
    'policy' => [
        'maxPerAuthorization' => '50.00',
        'maxPerPeriod' => [
                'amount' => '500.00',
                'period' => 'month'
        ]
    ],
    'expiresAt' => '2027-06-15T12:00:00.000Z',
    'approvalRedirect' => [
        'failureUrl' => 'https://merchant.example.com/mandate/approval/failed',
        'successUrl' => 'https://merchant.example.com/mandate/approval/success'
    ],
    'revocationRedirect' => [
        'failureUrl' => 'https://merchant.example.com/mandate/revocation/failed',
        'successUrl' => 'https://merchant.example.com/mandate/revocation/success'
    ],
    'customerDisplay' => [
        'merchantName' => 'Acme Store'
    ]
  ]),
  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.cdp.coinbase.com/platform/v2/mandates"

	payload := strings.NewReader("{\n  \"asset\": \"usdc\",\n  \"policy\": {\n    \"maxPerAuthorization\": \"50.00\",\n    \"maxPerPeriod\": {\n      \"amount\": \"500.00\",\n      \"period\": \"month\"\n    }\n  },\n  \"expiresAt\": \"2027-06-15T12:00:00.000Z\",\n  \"approvalRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/approval/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/approval/success\"\n  },\n  \"revocationRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/revocation/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/revocation/success\"\n  },\n  \"customerDisplay\": {\n    \"merchantName\": \"Acme Store\"\n  }\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.cdp.coinbase.com/platform/v2/mandates")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"asset\": \"usdc\",\n  \"policy\": {\n    \"maxPerAuthorization\": \"50.00\",\n    \"maxPerPeriod\": {\n      \"amount\": \"500.00\",\n      \"period\": \"month\"\n    }\n  },\n  \"expiresAt\": \"2027-06-15T12:00:00.000Z\",\n  \"approvalRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/approval/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/approval/success\"\n  },\n  \"revocationRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/revocation/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/revocation/success\"\n  },\n  \"customerDisplay\": {\n    \"merchantName\": \"Acme Store\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/mandates")

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  \"asset\": \"usdc\",\n  \"policy\": {\n    \"maxPerAuthorization\": \"50.00\",\n    \"maxPerPeriod\": {\n      \"amount\": \"500.00\",\n      \"period\": \"month\"\n    }\n  },\n  \"expiresAt\": \"2027-06-15T12:00:00.000Z\",\n  \"approvalRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/approval/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/approval/success\"\n  },\n  \"revocationRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/revocation/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/revocation/success\"\n  },\n  \"customerDisplay\": {\n    \"merchantName\": \"Acme Store\"\n  }\n}"

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

{
  "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "asset": "usdc",
  "policy": {
    "maxPerAuthorization": "50.00",
    "maxPerPeriod": {
      "amount": "500.00",
      "period": "month"
    }
  },
  "status": "created",
  "expiresAt": "2027-06-15T12:00:00.000Z",
  "url": "https://payments.coinbase.com/mandates/mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "approvalRedirect": {
    "failureUrl": "https://merchant.example.com/mandate/approval/failed",
    "successUrl": "https://merchant.example.com/mandate/approval/success"
  },
  "revocationRedirect": {
    "failureUrl": "https://merchant.example.com/mandate/revocation/failed",
    "successUrl": "https://merchant.example.com/mandate/revocation/success"
  },
  "customerDisplay": {
    "merchantName": "Acme Store"
  },
  "createdAt": "2025-06-15T12:00:00.000Z",
  "updatedAt": "2025-06-15T12:00:00.000Z"
}

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid mandate policy."
}

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."
}

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later."
}

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later."
}

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. Please try again later."
}

Mandates

Create a mandate

Creates a mandate denominated in asset. Optionally set policy to cap debits; if omitted, a Coinbase-configured monthly max applies. The response always includes the resolved policy.

Returns the mandate in created status with no source; it is not yet usable. Next step: have the customer approve it with Get wallet approval options then Approve a mandate with a wallet, which attaches the source and moves the mandate to approval_succeeded.

A mandate’s terms can’t be modified once created. To change them, cancel the mandate and create a new one.

POST

mandates

Create a mandate

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/mandates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "asset": "usdc",
  "policy": {
    "maxPerAuthorization": "50.00",
    "maxPerPeriod": {
      "amount": "500.00",
      "period": "month"
    }
  },
  "expiresAt": "2027-06-15T12:00:00.000Z",
  "approvalRedirect": {
    "failureUrl": "https://merchant.example.com/mandate/approval/failed",
    "successUrl": "https://merchant.example.com/mandate/approval/success"
  },
  "revocationRedirect": {
    "failureUrl": "https://merchant.example.com/mandate/revocation/failed",
    "successUrl": "https://merchant.example.com/mandate/revocation/success"
  },
  "customerDisplay": {
    "merchantName": "Acme Store"
  }
}
'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/mandates"

payload = {
    "asset": "usdc",
    "policy": {
        "maxPerAuthorization": "50.00",
        "maxPerPeriod": {
            "amount": "500.00",
            "period": "month"
        }
    },
    "expiresAt": "2027-06-15T12:00:00.000Z",
    "approvalRedirect": {
        "failureUrl": "https://merchant.example.com/mandate/approval/failed",
        "successUrl": "https://merchant.example.com/mandate/approval/success"
    },
    "revocationRedirect": {
        "failureUrl": "https://merchant.example.com/mandate/revocation/failed",
        "successUrl": "https://merchant.example.com/mandate/revocation/success"
    },
    "customerDisplay": { "merchantName": "Acme Store" }
}
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({
    asset: 'usdc',
    policy: {
      maxPerAuthorization: '50.00',
      maxPerPeriod: {amount: '500.00', period: 'month'}
    },
    expiresAt: '2027-06-15T12:00:00.000Z',
    approvalRedirect: {
      failureUrl: 'https://merchant.example.com/mandate/approval/failed',
      successUrl: 'https://merchant.example.com/mandate/approval/success'
    },
    revocationRedirect: {
      failureUrl: 'https://merchant.example.com/mandate/revocation/failed',
      successUrl: 'https://merchant.example.com/mandate/revocation/success'
    },
    customerDisplay: {merchantName: 'Acme Store'}
  })
};

fetch('https://api.cdp.coinbase.com/platform/v2/mandates', 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.cdp.coinbase.com/platform/v2/mandates",
  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([
    'asset' => 'usdc',
    'policy' => [
        'maxPerAuthorization' => '50.00',
        'maxPerPeriod' => [
                'amount' => '500.00',
                'period' => 'month'
        ]
    ],
    'expiresAt' => '2027-06-15T12:00:00.000Z',
    'approvalRedirect' => [
        'failureUrl' => 'https://merchant.example.com/mandate/approval/failed',
        'successUrl' => 'https://merchant.example.com/mandate/approval/success'
    ],
    'revocationRedirect' => [
        'failureUrl' => 'https://merchant.example.com/mandate/revocation/failed',
        'successUrl' => 'https://merchant.example.com/mandate/revocation/success'
    ],
    'customerDisplay' => [
        'merchantName' => 'Acme Store'
    ]
  ]),
  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.cdp.coinbase.com/platform/v2/mandates"

	payload := strings.NewReader("{\n  \"asset\": \"usdc\",\n  \"policy\": {\n    \"maxPerAuthorization\": \"50.00\",\n    \"maxPerPeriod\": {\n      \"amount\": \"500.00\",\n      \"period\": \"month\"\n    }\n  },\n  \"expiresAt\": \"2027-06-15T12:00:00.000Z\",\n  \"approvalRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/approval/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/approval/success\"\n  },\n  \"revocationRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/revocation/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/revocation/success\"\n  },\n  \"customerDisplay\": {\n    \"merchantName\": \"Acme Store\"\n  }\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.cdp.coinbase.com/platform/v2/mandates")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"asset\": \"usdc\",\n  \"policy\": {\n    \"maxPerAuthorization\": \"50.00\",\n    \"maxPerPeriod\": {\n      \"amount\": \"500.00\",\n      \"period\": \"month\"\n    }\n  },\n  \"expiresAt\": \"2027-06-15T12:00:00.000Z\",\n  \"approvalRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/approval/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/approval/success\"\n  },\n  \"revocationRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/revocation/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/revocation/success\"\n  },\n  \"customerDisplay\": {\n    \"merchantName\": \"Acme Store\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/mandates")

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  \"asset\": \"usdc\",\n  \"policy\": {\n    \"maxPerAuthorization\": \"50.00\",\n    \"maxPerPeriod\": {\n      \"amount\": \"500.00\",\n      \"period\": \"month\"\n    }\n  },\n  \"expiresAt\": \"2027-06-15T12:00:00.000Z\",\n  \"approvalRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/approval/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/approval/success\"\n  },\n  \"revocationRedirect\": {\n    \"failureUrl\": \"https://merchant.example.com/mandate/revocation/failed\",\n    \"successUrl\": \"https://merchant.example.com/mandate/revocation/success\"\n  },\n  \"customerDisplay\": {\n    \"merchantName\": \"Acme Store\"\n  }\n}"

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

{
  "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "asset": "usdc",
  "policy": {
    "maxPerAuthorization": "50.00",
    "maxPerPeriod": {
      "amount": "500.00",
      "period": "month"
    }
  },
  "status": "created",
  "expiresAt": "2027-06-15T12:00:00.000Z",
  "url": "https://payments.coinbase.com/mandates/mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "approvalRedirect": {
    "failureUrl": "https://merchant.example.com/mandate/approval/failed",
    "successUrl": "https://merchant.example.com/mandate/approval/success"
  },
  "revocationRedirect": {
    "failureUrl": "https://merchant.example.com/mandate/revocation/failed",
    "successUrl": "https://merchant.example.com/mandate/revocation/success"
  },
  "customerDisplay": {
    "merchantName": "Acme Store"
  },
  "createdAt": "2025-06-15T12:00:00.000Z",
  "updatedAt": "2025-06-15T12:00:00.000Z"
}

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid mandate policy."
}

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."
}

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later."
}

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later."
}

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. Please try again later."
}

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Headers

X-Idempotency-Key

string

An optional string request header for making requests safely retryable. When included, duplicate requests with the same key will return identical responses. Refer to our Idempotency docs for more information on using idempotency keys.

Required string length: 1 - 128

Body

application/json

A request to create a new mandate. The merchant is inferred from the API key. The mandate is returned in created status with no source. Attach a source next by approving the mandate, using Get wallet approval options then Approve a mandate with a wallet, which returns a pending approval; the mandate becomes approval_succeeded once that approval succeeds. The mandate is denominated in asset, fixed at creation. policy is optional. Omit it or send {} to default to a Coinbase-configured monthly max. The response includes the resolved policy. If you set maxPerPeriod, include both amount and period.

asset

string

required

The unit of account the mandate's policy caps are denominated in (e.g., 500 means 500 of this asset). Fixed at creation. This is only the denomination for the limits; the funding source may hold a different asset (for example, limits in usdc against a usdt source). Each authorization's amount is converted into this asset at authorization time to evaluate the caps, so the caps are always enforced in a single denomination.

Required string length: 1 - 42

Example:

"usdc"

policy

Mandate Policy · object

Optional. Omit or send {} to default to a Coinbase-configured monthly max. If you set maxPerPeriod, include both amount and period.

Show child attributes

Example:

{
  "maxPerAuthorization": "50.00",
  "maxPerPeriod": { "amount": "500.00", "period": "month" }
}

expiresAt

string<date-time>

The UTC ISO 8601 timestamp after which this mandate can no longer be authorized against. Omit for a mandate with no expiry.

Example:

"2027-06-15T12:00:00.000Z"

approvalRedirect

object

Optional merchant URLs used by the hosted mandate approval flow. The approval page redirects to successUrl when approval succeeds, or failureUrl when it fails. Omit to keep the customer on the Coinbase-hosted experience.

Show child attributes

Example:

{
  "failureUrl": "https://merchant.example.com/mandate/approval/failed",
  "successUrl": "https://merchant.example.com/mandate/approval/success"
}

revocationRedirect

object

Optional merchant URLs used by the hosted mandate revocation flow. The revocation page redirects to successUrl when revocation succeeds, or failureUrl when it fails. Omit to keep the customer on the Coinbase-hosted experience.

Show child attributes

Example:

{
  "failureUrl": "https://merchant.example.com/mandate/revocation/failed",
  "successUrl": "https://merchant.example.com/mandate/revocation/success"
}

customerDisplay

Mandate Customer Display · object

Merchant-provided display data shown to the customer on the hosted mandate pages. All fields are informational only. They are stored and returned as-is and do not affect mandate approval, authorization, or policy enforcement.

Show child attributes

Example:

{ "merchantName": "Acme Store" }

metadata

object

Optional metadata as key-value pairs. Use this to store additional structured information on a resource, such as customer IDs, order references, or any application-specific data. Up to 10 key/value pairs may be provided. Keys and values are both strings. Keys must be ≤ 40 characters; values must be ≤ 500 characters.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

Response

Successfully created mandate.

A durable, revocable standing authorization to debit a funding source without the customer present each time, within its policy caps. Payment sessions draw against it by referencing its mandateId.

source is set once an approval succeeds. status reflects the most recent action; the approvedAt, canceledAt, and revokedAt timestamps are the durable record of what has happened. Ending one mandate does not affect other mandates on the same source.

mandateId

string

required

The unique identifier of the mandate.

Pattern: ^mandate_[a-f0-9\-]{36}$

Example:

"mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

asset

string

required

Required string length: 1 - 42

Example:

"usdc"

policy

Mandate Policy · object

required

Debit caps. Always present. If you omitted policy at create, this is a Coinbase-configured monthly max.

Show child attributes

Example:

{
  "maxPerAuthorization": "50.00",
  "maxPerPeriod": { "amount": "500.00", "period": "month" }
}

status

enum<string>

required

The current status of the mandate.

Available options:

created,

approval_pending,

approval_succeeded,

approval_failed,

revocation_pending,

revocation_succeeded,

revocation_failed,

canceled

Example:

"approval_succeeded"

createdAt

string<date-time>

required

The UTC ISO 8601 timestamp at which the mandate was created.

Example:

"2025-06-15T12:00:00.000Z"

updatedAt

string<date-time>

required

The UTC ISO 8601 timestamp at which the mandate was last updated.

Example:

"2025-06-15T12:00:00.000Z"

source

Mandate Source Wallet · object

The funding source the mandate draws against. Set when an approval succeeds. Not present before the mandate is approval_succeeded.

Show child attributes

Example:

{
  "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
  "network": "base",
  "asset": "usdc"
}

expiresAt

string<date-time>

The UTC ISO 8601 timestamp after which the mandate can no longer be authorized against. Authorization attempts after this time return 422; status does not change. Omit for no expiry.

Example:

"2027-06-15T12:00:00.000Z"

url

string<uri>

Hosted page where the customer approves this mandate. Present only before the mandate reaches approval_succeeded; complemented by revocationUrl afterward.

Required string length: 11 - 2048

Pattern: ^https?://.*$

Example:

"https://payments.coinbase.com/mandates/mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

revocationUrl

string<uri>

Hosted page where the customer can remove their spending allowance for this mandate. Present once the mandate has a source (from approval_succeeded onward); absent before approval, when there is nothing to revoke.

Required string length: 11 - 2048

Pattern: ^https?://.*$

Example:

"https://payments.coinbase.com/mandates/mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/revoke"

approvalRedirect

object

Optional merchant URLs used by the hosted mandate approval flow. The approval page redirects to successUrl when approval succeeds, or failureUrl when it fails. When omitted, the approval page keeps the customer on the Coinbase-hosted experience.

Show child attributes

Example:

{
  "failureUrl": "https://merchant.example.com/mandate/approval/failed",
  "successUrl": "https://merchant.example.com/mandate/approval/success"
}

revocationRedirect

object

Optional merchant URLs used by the hosted mandate revocation flow. The revocation page redirects to successUrl when revocation succeeds, or failureUrl when it fails. When omitted, the revocation page keeps the customer on the Coinbase-hosted experience.

Show child attributes

Example:

{
  "failureUrl": "https://merchant.example.com/mandate/revocation/failed",
  "successUrl": "https://merchant.example.com/mandate/revocation/success"
}

customerDisplay

Mandate Customer Display · object

Show child attributes

Example:

{ "merchantName": "Acme Store" }

approvedAt

string<date-time>

The UTC ISO 8601 timestamp at which an approval succeeded and the mandate became usable. Present only once the mandate has been approved; set once, on the successful approval, and unchanged by later transitions. Its presence is the durable signal that the mandate was approved, independent of status.

Example:

"2026-08-21T13:55:00.000Z"

canceledAt

string<date-time>

The UTC ISO 8601 timestamp at which the merchant canceled the mandate off-chain. Present only once the mandate has been canceled. Canceling does not touch the on-chain spending allowance; check revokedAt for that.

Example:

"2026-08-21T14:02:00.000Z"

revokedAt

string<date-time>

The UTC ISO 8601 timestamp at which the spending allowance was removed on-chain by a wallet revocation. Present only once that has happened. Its presence is the single signal that the allowance is gone, independent of status (for example, it can be set on a canceled mandate whose allowance was later cleaned up).

Example:

"2026-08-21T14:12:00.000Z"

metadata

object

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}