Skip to content

Update a merchant

PUT
/v1/admin/merchants/{merchant_id}/

Merges the fields you send into the merchant; nested objects such as tags and contact_persons are merged too. company_name is required. A merchant with status ended can't be changed. The IBAN of bank_account can't be changed with this call.

Authorization

apiKey
headerAuthorizationBasic <token>

HTTP Basic authentication with an admin API key as the username and an empty password.

Path Parameters

merchant_id*string

The ID of the merchant.

Formatuuid

Request Body

application/json
  1. body

A merchant. Most fields can only be changed with the Boarding API; merchants can't change them with the Merchant Self-Service API.

status?string

pending until the merchant is live, active when live. Use ending or ended to end the merchant's contract, and inactive when the application was rejected. See Statuses.

Value in"pending""active""ending""ended""inactive"
company_name*string
external_merchant_id?|

Your own identifier of the merchant.

external_reference_number?|

An external reference number, shown as client reference number in the Admin portal.

email?string
Formatemail
phone_numbers?array<string>

Phone numbers. Use the international format, such as +31201234567.

website_url?|
Formaturi
addresses?array<>
business_type?string|null
chamber_of_commerce_number?string|null
vat_number?string|null
vat_class?|
Value in"nl-high""reverse-charge"null
contact_persons?

The general, technical and financial contact persons, as user IDs.

locale?|

Language and region, such as en_GB or nl-NL.

timezone?|

IANA timezone, such as Europe/Amsterdam.

district_court?|

The district court, for German merchants.

bank_account?

The bank account of the merchant. Changing the IBAN needs a change request approved by a second user.

base_permissions?

Permissions by path, such as /orders/**, with per HTTP method (GET, POST, PUT, DELETE or * for all) true or false. Payment methods are permissions on /payment-methods/<method>/ with POST. See Permissions.

contracts?

The merchant's contracts, by contract type, each with its fields. See Processor contracts.

save_payment_method_enabled?boolean

Whether shoppers can save their payment method on the hosted payment page.

tags?

Key-value tags, copied to new orders and transactions as merchant_tags. See Merchant tags.

priceplan_id?|

The price plan of the earlier billing system. Ginger Payout uses the price plan of the payout entity.

payout_system?string

Earlier billing system. Whether the payout is gross or net.

Value in"gross""net"
payout_scheme?

Earlier billing system. The payout frequency of the merchant.

invoice_charge_method?string

Earlier billing system. do-not-charge only with payout_system gross.

Value in"invoice-transfer""do-not-charge"
settings?

Merchant settings.

Response Body

The updated merchant.

application/json
  1. response

A merchant. Most fields can only be changed with the Boarding API; merchants can't change them with the Merchant Self-Service API.

id?string
Formatuuid
created?string
Formatdate-time
modified?|
Formatdate-time
status?string

pending until the merchant is live, active when live. Use ending or ended to end the merchant's contract, and inactive when the application was rejected. See Statuses.

Value in"pending""active""ending""ended""inactive"
company_name*string
external_merchant_id?|

Your own identifier of the merchant.

external_reference_number?|

An external reference number, shown as client reference number in the Admin portal.

email?string
Formatemail
phone_numbers?array<string>

Phone numbers. Use the international format, such as +31201234567.

website_url?|
Formaturi
addresses?array<>
business_type?string|null
chamber_of_commerce_number?string|null
vat_number?string|null
vat_class?|
Value in"nl-high""reverse-charge"null
contact_persons?

The general, technical and financial contact persons, as user IDs.

locale?|

Language and region, such as en_GB or nl-NL.

timezone?|

IANA timezone, such as Europe/Amsterdam.

district_court?|

The district court, for German merchants.

bank_account?

The bank account of the merchant. Changing the IBAN needs a change request approved by a second user.

base_permissions?

Permissions by path, such as /orders/**, with per HTTP method (GET, POST, PUT, DELETE or * for all) true or false. Payment methods are permissions on /payment-methods/<method>/ with POST. See Permissions.

contracts?

The merchant's contracts, by contract type, each with its fields. See Processor contracts.

save_payment_method_enabled?boolean

Whether shoppers can save their payment method on the hosted payment page.

tags?

Key-value tags, copied to new orders and transactions as merchant_tags. See Merchant tags.

priceplan_id?|

The price plan of the earlier billing system. Ginger Payout uses the price plan of the payout entity.

payout_system?string

Earlier billing system. Whether the payout is gross or net.

Value in"gross""net"
payout_scheme?

Earlier billing system. The payout frequency of the merchant.

invoice_charge_method?string

Earlier billing system. do-not-charge only with payout_system gross.

Value in"invoice-transfer""do-not-charge"
settings?

Merchant settings.

curl -X PUT 'https://api.example.com/v1/admin/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/' \  --user "$API_KEY:" \  -H 'Content-Type: application/json' \  -d '{  "company_name": "Acme Coffee B.V.",  "status": "active"}'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "created": "2019-08-24T14:15:22Z",  "modified": "2019-08-24T14:15:22Z",  "status": "pending",  "company_name": "Acme Coffee B.V.",  "external_merchant_id": "string",  "external_reference_number": "string",  "email": "user@example.com",  "phone_numbers": [    "string"  ],  "website_url": "http://example.com",  "addresses": [    {      "type": "billing",      "address_line_1": "Coffee Street 1",      "address_line_2": "string",      "postal_code": "1011 AB",      "city": "Amsterdam",      "address": "string",      "country": "NL"    }  ],  "business_type": "string",  "chamber_of_commerce_number": "string",  "vat_number": "string",  "vat_class": "nl-high",  "contact_persons": {    "general": "string",    "technical": "string",    "financial": "string"  },  "locale": "string",  "timezone": "string",  "district_court": "string",  "bank_account": {    "holder_name": "string",    "currency": "EUR",    "iban": "string",    "bic": "string"  },  "base_permissions": {    "property1": {      "GET": true,      "POST": true,      "PUT": true,      "DELETE": true,      "*": true    },    "property2": {      "GET": true,      "POST": true,      "PUT": true,      "DELETE": true,      "*": true    }  },  "contracts": {    "property1": {      "fields": {        "one_click_enabled": true,        "recurring_enabled": true,        "gateway": "string",        "credit_limit": 0,        "begin_date": "2026-11-01",        "end_date": "string",        "funding_delay": 0      }    },    "property2": {      "fields": {        "one_click_enabled": true,        "recurring_enabled": true,        "gateway": "string",        "credit_limit": 0,        "begin_date": "2026-11-01",        "end_date": "string",        "funding_delay": 0      }    }  },  "save_payment_method_enabled": true,  "tags": {    "property1": "string",    "property2": "string"  },  "priceplan_id": "string",  "payout_system": "gross",  "payout_scheme": {    "frequency": "never",    "weekdays": [      "monday"    ],    "monthdays": [      1    ]  },  "invoice_charge_method": "invoice-transfer",  "settings": {}}