---
title: Create customer payment method switch
slug: reference/create-customer-payment-method-switch
docTags:
createdAt: 2025-08-21T21:09:26.155Z
---
{
"id": "AC1vVGF4K6MS2tY9q_rc_",
"type": "api-oas-v2",
"data": {
"method": "POST",
"url": "https://app.amberflo.io/customers/payment-method/switch",
"servers": [
{
"url": "https://app.amberflo.io/customers/payment-method/switch"
}
],
"name": "Create customer payment method switch",
"description": "Creates a new payment method switch for a customer, automatically canceling any future scheduled switches.\nUse this endpoint to change a customer's payment provider and billing configuration.
\nUse this endpoint to:
\n\n- Switch customer from one payment provider to another
\n- Schedule payment method changes with specific timing
\n- Override previously scheduled payment method switches
\n- Configure customer billing transitions
\n
\nImportant: This operation cancels all future scheduled switches for the customer.
",
"contentType": "application/json",
"request": {
"pathParameters": [],
"headerParameters": [],
"queryParameters": [],
"bodyDataParameters": [
{
"kind": "optional",
"name": "body",
"type": "object",
"description": "Payment method switch configuration including target provider, timing, and transition details",
"customType": "customer.payment_method.CustomerPaymentMethodSwitch.in",
"schema": [
{
"name": "customerId",
"kind": "required",
"type": "string",
"description": "Unique customer identifier for whom the payment method switch configuration applies and payment transitions will be executed.",
"example": ""
},
{
"name": "sourcePaymentType",
"kind": "optional",
"type": "string",
"description": "Current billing system enumeration indicating the payment provider platform being transitioned away from during the switch operation.",
"modelRef": "#/components/schemas/customer.payment_method.BillingSystem.in",
"customType": "customer.payment_method.BillingSystem.in",
"schema": []
},
{
"name": "sourcePaymentId",
"kind": "optional",
"type": "string",
"description": "Payment provider connection identifier currently active before the switch, referencing existing billing system configuration and account settings.",
"example": ""
},
{
"name": "targetPaymentType",
"kind": "required",
"type": "string",
"description": "Target billing system enumeration specifying the destination payment provider platform to activate after the scheduled switch execution.",
"modelRef": "#/components/schemas/customer.payment_method.BillingSystem.in",
"customType": "customer.payment_method.BillingSystem.in",
"schema": []
},
{
"name": "targetPaymentId",
"kind": "required",
"type": "string",
"description": "Payment provider connection identifier for the new billing system, referencing target account payment settings and integration configurations.",
"example": ""
},
{
"name": "targetCustomerIdentifier",
"kind": "required",
"type": "string",
"description": "Customer-specific identifier within the target payment provider system, enabling billing operations and payment processing in the destination platform.",
"example": ""
},
{
"name": "switchTimeInSeconds",
"kind": "required",
"type": "integer",
"description": "Unix timestamp in seconds defining the exact moment when payment provider transition activates, evaluated against invoice start times.",
"example": 0
}
],
"modelRef": "#/components/schemas/customer.payment_method.CustomerPaymentMethodSwitch.in",
"isExpanded": true
}
],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "apiKey",
"name": "X-API-KEY",
"kind": "optional",
"type": "apiKey",
"in": "header"
}
]
},
"responses": [
{
"statusCode": "200",
"description": "Successfully created payment method switch with confirmation details and effective timing",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "Customer payment method switch configuration defining the scheduled transition from one billing system to another, including audit timestamps and execution status for payment provider migration tracking.",
"customType": "customer.payment_method.CustomerPaymentMethodSwitch.out",
"schema": [
{
"name": "customerId",
"kind": "required",
"type": "string",
"description": "Unique customer identifier for whom the payment method switch configuration applies and payment transitions will be executed.",
"example": ""
},
{
"name": "sourcePaymentType",
"kind": "optional",
"type": "string",
"description": "Current billing system enumeration indicating the payment provider platform being transitioned away from during the switch operation.",
"modelRef": "#/components/schemas/customer.payment_method.BillingSystem.in",
"customType": "customer.payment_method.BillingSystem.in",
"schema": []
},
{
"name": "sourcePaymentId",
"kind": "optional",
"type": "string",
"description": "Payment provider connection identifier currently active before the switch, referencing existing billing system configuration and account settings.",
"example": ""
},
{
"name": "targetPaymentType",
"kind": "required",
"type": "string",
"description": "Target billing system enumeration specifying the destination payment provider platform to activate after the scheduled switch execution.",
"modelRef": "#/components/schemas/customer.payment_method.BillingSystem.in",
"customType": "customer.payment_method.BillingSystem.in",
"schema": []
},
{
"name": "targetPaymentId",
"kind": "required",
"type": "string",
"description": "Payment provider connection identifier for the new billing system, referencing target account payment settings and integration configurations.",
"example": ""
},
{
"name": "targetCustomerIdentifier",
"kind": "required",
"type": "string",
"description": "Customer-specific identifier within the target payment provider system, enabling billing operations and payment processing in the destination platform.",
"example": ""
},
{
"name": "switchTimeInSeconds",
"kind": "required",
"type": "integer",
"description": "Unix timestamp in seconds defining the exact moment when payment provider transition activates, evaluated against invoice start times.",
"example": 0
},
{
"name": "createdTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp in seconds recording when the payment method switch configuration was initially created and stored in the system.",
"example": 0
},
{
"name": "updatedTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp in seconds tracking the most recent modification to the payment method switch configuration for audit and versioning purposes.",
"example": 0
}
],
"modelRef": "#/components/schemas/customer.payment_method.CustomerPaymentMethodSwitch.out",
"isExpanded": true
}
]
},
{
"statusCode": "400",
"description": "Invalid switch configuration, unsupported payment provider, or malformed request body",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "401",
"description": "Authentication required or invalid API key provided",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "403",
"description": "Insufficient permissions to modify customer payment methods",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "404",
"description": "Customer not found or target payment provider not configured",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "409",
"description": "Conflicting payment method switch already in progress for this customer",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "500",
"description": "Internal server error occurred while creating payment method switch",
"jsonExample": "",
"isExpanded": true
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "gC_IlL7JARO3m9zd7tiaP",
"language": "curl",
"label": "cURL",
"code": "curl --request POST \\\n --url https://app.amberflo.io/customers/payment-method/switch \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"customerId\": \"\",\n \"targetPaymentType\": \"\",\n \"targetPaymentId\": \"\",\n \"targetCustomerIdentifier\": \"\",\n \"switchTimeInSeconds\": 0\n }'"
},
{
"id": "Jyi2xcg-EuyY0YpLd7wOr",
"language": "javascript",
"label": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"customerId\": \"\",\n \"targetPaymentType\": \"\",\n \"targetPaymentId\": \"\",\n \"targetCustomerIdentifier\": \"\",\n \"switchTimeInSeconds\": 0\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/customers/payment-method/switch\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "6XTMGHxTN94cLVcrWbzOF",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/customers/payment-method/switch\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"customerId\": \"\",\n \"targetPaymentType\": \"\",\n \"targetPaymentId\": \"\",\n \"targetCustomerIdentifier\": \"\",\n \"switchTimeInSeconds\": 0\n})\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "UMphDbJ0nmpyzgftfphMy",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/customers/payment-method/switch\"\n\npayload = json.dumps({\n \"customerId\": \"\",\n \"targetPaymentType\": \"\",\n \"targetPaymentId\": \"\",\n \"targetCustomerIdentifier\": \"\",\n \"switchTimeInSeconds\": 0\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
}
],
"selectedLanguageId": "gC_IlL7JARO3m9zd7tiaP"
},
"results": {
"languages": [
{
"id": "response-0-200",
"language": "200",
"code": "// Successfully created payment method switch with confirmation details and effective timing\n{\n \"customerId\": \"\",\n \"sourcePaymentType\": \"\",\n \"sourcePaymentId\": \"\",\n \"targetPaymentType\": \"\",\n \"targetPaymentId\": \"\",\n \"targetCustomerIdentifier\": \"\",\n \"switchTimeInSeconds\": \"\",\n \"createdTimeInSeconds\": \"\",\n \"updatedTimeInSeconds\": \"\"\n}"
},
{
"id": "response-1-400",
"language": "400",
"code": "// Invalid switch configuration, unsupported payment provider, or malformed request body\n"
},
{
"id": "response-2-401",
"language": "401",
"code": "// Authentication required or invalid API key provided\n"
},
{
"id": "response-3-403",
"language": "403",
"code": "// Insufficient permissions to modify customer payment methods\n"
},
{
"id": "response-4-404",
"language": "404",
"code": "// Customer not found or target payment provider not configured\n"
},
{
"id": "response-5-409",
"language": "409",
"code": "// Conflicting payment method switch already in progress for this customer\n"
},
{
"id": "response-6-500",
"language": "500",
"code": "// Internal server error occurred while creating payment method switch\n"
}
],
"selectedLanguageId": "response-0-200"
}
},
"children": [
{
"text": ""
}
]
}