Definition
https://sandbox.bluesnap.com/services/2/catalog/custom-parameters
The Create Custom Parameter enables you to create new custom parameters in your BlueSnap account.
Custom parameters are additional fields or values (visible or hidden) that you can add to your checkout page. For example, you might use a hidden custom field to pass values along to your own internal system. Or you might use a visible custom field on your checkout page to gather additional information from your shoppers. For example, if you need to obtain the shopper's T-shirt size, you can add this as a custom field on the checkout page and require that the shopper select a size. To add the parameter to your checkout page, pass the response value (for example, 16807 in the response below) as the sku-custom-parameter in an Update SKU API call.
Custom parameters are passed in reports, Instant Payment Notifications (IPN), and sales confirmation emails.
Creating SKU-specific custom paramaters in the BlueSnap merchant console
The custom parameters you create through this web service are not linked to any specific SKU/contract.
If you would like to create custom parameters that are connected to a specific contract, you can do that in the BlueSnap merchant console. For instructions, see Setting up custom fields.
Request Content
custom-parameter required, contains the following properties (see custom-parameter):
| Property | Type | Required |
|---|---|---|
custom-param-title | string | required |
active | boolean | optional |
mandatory | boolean | optional |
custom-param-settings container required, contains the following properties (see custom-param-settings):
| Property | Type | Required |
|---|---|---|
custom-param-type | string | required |
short-text-type | container | optional (see short-text-type) |
visual-settings | container | optional (see visual-settings) |
fixed-selection-type | container | optional (see fixed-selection-type) |
merchant-value-type | container | optional (see merchant-value-type) |
Response Details
If successful, the response HTTP status code is 201 Created.
The Location response header contains the URI of the newly created custom-parameter resource.
There is no content in the response body.
For details about possible errors, see: General Errors and Catalog Errors.
Examples
Request Examples
curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<custom-parameter xmlns="http://ws.plimus.com">
<custom-param-title>Example Checkbox</custom-param-title>
<active>true</active>
<mandatory>true</mandatory>
<custom-param-settings>
<custom-param-type>boolean</custom-param-type>
<visual-settings>
<title-alignment>LEFT</title-alignment>
</visual-settings>
</custom-param-settings>
</custom-parameter>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<custom-parameter xmlns="http://ws.plimus.com">
<custom-param-title>Example ready-only input</custom-param-title>
<active>true</active>
<mandatory>true</mandatory>
<custom-param-settings>
<custom-param-type>read-only</custom-param-type>
<visual-settings>
<title-alignment>LEFT</title-alignment>
</visual-settings>
</custom-param-settings>
</custom-parameter>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<custom-parameter xmlns="http://ws.plimus.com">
<custom-param-title>Where did you hear about us?</custom-param-title>
<active>true</active>
<mandatory>true</mandatory>
<custom-param-settings>
<custom-param-type>short-text</custom-param-type>
<short-text-type>
<maximum-length>2000</maximum-length>
<minimum-length>7</minimum-length>
<regex-validation>[a-zA-Z]</regex-validation>
</short-text-type>
<visual-settings>
<title-alignment>LEFT</title-alignment>
</visual-settings>
</custom-param-settings>
</custom-parameter>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<custom-parameter xmlns="http://ws.plimus.com">
<custom-param-title>Where did you hear about us?</custom-param-title>
<active>true</active>
<mandatory>true</mandatory>
<custom-param-settings>
<custom-param-type>short-text</custom-param-type>
<short-text-type>
<maximum-length>2000</maximum-length>
<minimum-length>7</minimum-length>
</short-text-type>
<visual-settings>
<title-alignment>LEFT</title-alignment>
</visual-settings>
</custom-param-settings>
</custom-parameter>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<custom-parameter xmlns="http://ws.plimus.com">
<custom-param-title>Please share any feedback</custom-param-title>
<active>true</active>
<mandatory>true</mandatory>
<custom-param-settings>
<custom-param-type>long-text</custom-param-type>
<long-text-type>
<maximum-length>2000</maximum-length>
<minimum-length>7</minimum-length>
</long-text-type>
<visual-settings>
<title-alignment>LEFT</title-alignment>
</visual-settings>
</custom-param-settings>
</custom-parameter>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameter \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<custom-parameter xmlns="http://ws.plimus.com">
<custom-param-title>Where did you hear about us?</custom-param-title>
<active>true</active>
<mandatory>true</mandatory>
<custom-param-settings>
<custom-param-type>fixed selection</custom-param-type>
<fixed-selection-type>
<drop-down-values>
<drop-down-value>a</drop-down-value>
<drop-down-value>b</drop-down-value>
<drop-down-value>c</drop-down-value>
</drop-down-values>
</fixed-selection-type>
</custom-param-settings>
</custom-parameter>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<custom-parameter xmlns="http://ws.plimus.com">
<custom-param-title>MerchantSpecificId</custom-param-title>
<active>true</active>
<mandatory>true</mandatory>
<custom-param-settings>
<custom-param-type>merchant passed value</custom-param-type>
<merchant-value-type>
<maximum-length>2000</maximum-length>
<minimum-length>7</minimum-length>
</merchant-value-type>
<visual-settings>
<title-alignment>LEFT</title-alignment>
</visual-settings>
</custom-param-settings>
</custom-parameter>'
Response Example
HTTP/ 1.1 201 Created
Location: https://sandbox.bluesnap.com/services/2/catalog/custom-parameters/16807