Create Custom Parameter · BlueSnap Developer Hub

{"_id":"5b19742cb3baf90003cab505","category":{"_id":"5b19742cb3baf90003cab4ec","version":"5b19742cb3baf90003cab5ae","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-05-12T15:22:00.041Z","from_sync":false,"order":4,"slug":"coupon","title":"Catalog"},"project":"57336fd5a6a9c40e00e13a0b","user":"560d5913af97231900938124","parentDoc":null,"version":{"_id":"5b19742cb3baf90003cab5ae","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"5adf4e59ac13b80003d23152","createdAt":"2018-04-24T15:33:45.744Z","releaseDate":"2018-04-24T15:33:45.744Z","categories":["5b19742cb3baf90003cab4e8","5b19742cb3baf90003cab4e9","5b19742cb3baf90003cab4ea","5b19742cb3baf90003cab4eb","5b19742cb3baf90003cab4ec","5b19742cb3baf90003cab4ed","5b19742cb3baf90003cab4ee","5b19742cb3baf90003cab4ef","5b19742cb3baf90003cab4f0","5b19742cb3baf90003cab4f1","5b19742cb3baf90003cab4f2"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"3.26 Release","version_clean":"8976.0.0-Extended","version":"8976-Extended"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-05-12T15:20:43.016Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"code":"","language":"text"}]},"settings":"","examples":{"codes":[]},"method":"post","auth":"optional","params":[],"url":""},"isReference":true,"order":7,"body":"##Definition\nhttps://sandbox.bluesnap.com/services/2/catalog/custom-parameters\n\n<hr>\n\n##Documentation\nThe Create Custom Parameter enables you to create new custom parameters in your BlueSnap account. \n\nCustom parameters are additional fields or values (either 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. \n\nCustom parameters are passed in reports, Instant Payment Notifications (IPN), and sales confirmation emails. \n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"Creating SKU-specific custom paramaters in the BlueSnap merchant console\",\n \"body\": \"The custom parameters you create through this web service are not linked to any specific SKU/contract.\\n\\nIf 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](http://support.bluesnap.com/docs/custom-fields#section-setting-up-custom-fields).\"\n}\n[/block]\n###Request Content\n`custom-parameter`    **required**, contains the following properties (see [custom-parameter](doc:custom-parameter)):\n      `custom-param-title` *string*    **required**\n      `active` *boolean*    optional\n      `mandatory` *boolean*    optional\n      `custom-param-settings` *container*    **required**, contains the following properties (see [custom-param-settings](doc:custom-param-settings)):\n          `custom-param-type` *string*    **required**\n          `short-text-type` *container*    optional (see [short-text-type](doc:short-text-type))\n          `visual-settings` *container*    optional (see [visual-settings](doc:visual-settings))\n          `fixed-selection-type` *container*    optional (see [fixed-selection-type](doc:fixed-selection-type))\n          `merchant-value-type` *container*    optional (see [merchant-value-type](doc:merchant-value-type))\n\n###Response Details\nIf successful, the response HTTP status code is 201 Created.\nThe Location response header contains the URI of the newly created `custom-parameter` resource.\nThere is no content in the response body.\nFor details about possible errors, see: [General Errors](doc:general-errors) and [Catalog Errors](doc:catalog-errors).\n\n<hr>\n\n##Examples\n\n###Request Examples\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<custom-parameter xmlns=\\\"http://ws.plimus.com\\\">\\n <custom-param-title>Example Checkbox</custom-param-title>\\n <active>true</active>\\n <mandatory>true</mandatory>\\n <custom-param-settings>\\n <custom-param-type>boolean</custom-param-type>\\n <visual-settings>\\n <title-alignment>LEFT</title-alignment>\\n </visual-settings>\\n </custom-param-settings>\\n</custom-parameter>'\",\n \"language\": \"curl\",\n \"name\": \"Create Custom Parameter Request: checkbox\"\n },\n {\n \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<custom-parameter xmlns=\\\"http://ws.plimus.com\\\">\\n <custom-param-title>Example ready-only input</custom-param-title>\\n <active>true</active>\\n <mandatory>true</mandatory>\\n <custom-param-settings>\\n <custom-param-type>read-only</custom-param-type>\\n <visual-settings>\\n <title-alignment>LEFT</title-alignment>\\n </visual-settings>\\n </custom-param-settings>\\n</custom-parameter>'\",\n \"language\": \"curl\",\n \"name\": \"read-only input\"\n },\n {\n \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<custom-parameter xmlns=\\\"http://ws.plimus.com\\\">\\n <custom-param-title>Where did you hear about us?</custom-param-title>\\n <active>true</active>\\n <mandatory>true</mandatory>\\n <custom-param-settings>\\n <custom-param-type>short-text</custom-param-type>\\n <short-text-type>\\n <maximum-length>2000</maximum-length>\\n <minimum-length>7</minimum-length>\\n <regex-validation>[a-zA-Z]</regex-validation>\\n </short-text-type>\\n <visual-settings>\\n <title-alignment>LEFT</title-alignment>\\n </visual-settings>\\n </custom-param-settings>\\n</custom-parameter>'\",\n \"language\": \"curl\",\n \"name\": \"short text input\"\n },\n {\n \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<custom-parameter xmlns=\\\"http://ws.plimus.com\\\">\\n <custom-param-title>Where did you hear about us?</custom-param-title>\\n <active>true</active>\\n <mandatory>true</mandatory>\\n <custom-param-settings>\\n <custom-param-type>short-text</custom-param-type>\\n <short-text-type>\\n <maximum-length>2000</maximum-length>\\n <minimum-length>7</minimum-length>\\n </short-text-type>\\n <visual-settings>\\n <title-alignment>LEFT</title-alignment>\\n </visual-settings>\\n </custom-param-settings>\\n</custom-parameter>'\",\n \"language\": \"curl\",\n \"name\": \"short text input without regex\"\n },\n {\n \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<custom-parameter xmlns=\\\"http://ws.plimus.com\\\">\\n <custom-param-title>Please share any feedback</custom-param-title>\\n <active>true</active>\\n <mandatory>true</mandatory>\\n <custom-param-settings>\\n <custom-param-type>long-text</custom-param-type>\\n <long-text-type>\\n <maximum-length>2000</maximum-length>\\n <minimum-length>7</minimum-length>\\n </long-text-type>\\n <visual-settings>\\n <title-alignment>LEFT</title-alignment>\\n </visual-settings>\\n </custom-param-settings>\\n</custom-parameter>'\",\n \"language\": \"curl\",\n \"name\": \"text area\"\n },\n {\n \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameter \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<custom-parameter xmlns=\\\"http://ws.plimus.com\\\">\\n <custom-param-title>Where did you hear about us?</custom-param-title>\\n <active>true</active>\\n <mandatory>true</mandatory>\\n <custom-param-settings>\\n <custom-param-type>fixed selection</custom-param-type>\\n <fixed-selection-type>\\n <drop-down-values>\\n <drop-down-value>a</drop-down-value>\\n <drop-down-value>b</drop-down-value>\\n <drop-down-value>c</drop-down-value>\\n </drop-down-values>\\n </fixed-selection-type>\\n </custom-param-settings>\\n</custom-parameter>'\",\n \"language\": \"curl\",\n \"name\": \"dropdown\"\n },\n {\n \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/catalog/custom-parameters \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<custom-parameter xmlns=\\\"http://ws.plimus.com\\\">\\n <custom-param-title>MerchantSpecificId</custom-param-title>\\n <active>true</active>\\n <mandatory>true</mandatory>\\n <custom-param-settings>\\n <custom-param-type>merchant passed value</custom-param-type>\\n <merchant-value-type>\\n <maximum-length>2000</maximum-length>\\n <minimum-length>7</minimum-length>\\n </merchant-value-type>\\n <visual-settings>\\n <title-alignment>LEFT</title-alignment>\\n </visual-settings>\\n </custom-param-settings>\\n</custom-parameter>'\",\n \"language\": \"curl\",\n \"name\": \"hidden parameter\"\n }\n ]\n}\n[/block]\n###Response Example\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"HTTP/ 1.1 201 Created\\nLocation: https://sandbox.bluesnap.com/services/2/catalog/custom-parameters/16807\",\n \"language\": \"http\",\n \"name\": \"Create Custom Parameter Response: 201 Created\"\n }\n ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n<hr>\n\n##Example Descriptions\n\n###Create Custom Parameter: checkbox\nTo create a checkbox custom parameter, set the `custom-param-type` attribute to **boolean**, in lower case.\n\n###Create Custom Parameter: read-only input\nTo create a read-only custom parameter, set the `custom-param-type` attribute to **read-only**, in lower case.\n\n###Create Custom Parameter: short text input with/without regex\nTo create a short text custom parameter, set the `custom-param-type` attribute to **short-text**, in lower case. You can optionally define a regex to validate the input by sending it in the `regex-validation` field.\n\n###Create Custom Parameter: text area\nTo create a text area custom parameter, set the `custom-param-type` attribute to **long-text**, in lower case.\n\n###Create Custom Parameter: dropdown\nTo create a dropdown custom parameter, set the `custom-param-type` attribute to **fixed selection**, in lower case.\n\n###Create Custom Parameter: hidden parameter\nTo create a hidden custom parameter, set the `custom-param-type` attribute to **merchant passed value**, in lower case.\n\n \n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>","excerpt":"","slug":"create-custom-parameter","type":"endpoint","title":"Create Custom Parameter"}

Definition

https://sandbox.bluesnap.com/services/2/catalog/custom-parameters

Documentation

The Create Custom Parameter enables you to create new custom parameters in your BlueSnap account.

Custom parameters are additional fields or values (either 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.

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):
      custom-param-title string    required
      active boolean    optional
      mandatory boolean    optional
      custom-param-settings container    required, contains the following properties (see custom-param-settings):
          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

Create Custom Parameter Request: checkbox

read-only input

short text input

short text input without regex

text area

dropdown

hidden 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 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

Create Custom Parameter Response: 201 Created

HTTP/ 1.1 201 Created
Location: https://sandbox.bluesnap.com/services/2/catalog/custom-parameters/16807

Example Descriptions

Create Custom Parameter: checkbox

To create a checkbox custom parameter, set the custom-param-type attribute to boolean, in lower case.

Create Custom Parameter: read-only input

To create a read-only custom parameter, set the custom-param-type attribute to read-only, in lower case.

Create Custom Parameter: short text input with/without regex

To create a short text custom parameter, set the custom-param-type attribute to short-text, in lower case. You can optionally define a regex to validate the input by sending it in the regex-validation field.

Create Custom Parameter: text area

To create a text area custom parameter, set the custom-param-type attribute to long-text, in lower case.

Create Custom Parameter: dropdown

To create a dropdown custom parameter, set the custom-param-type attribute to fixed selection, in lower case.

Create Custom Parameter: hidden parameter

To create a hidden custom parameter, set the custom-param-type attribute to merchant passed value, in lower case.

BlueSnap Developer Hub

Extended Payment API

Orders

Shopping Context

Shoppers

Catalog

Subscriptions

Wallets

Errors

Resources

Test Data & Codes

Guides & Tools

postCreate Custom Parameter