--- title: Create Metadata Mappings slug: create-metadata-mappings docTags: createdAt: 2026-08-25T19:28:59.170Z --- { "id": "lIAifYNsS8m0hCjKhxL4i", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.nue.io/v1/stripe/metadata-mapping", "servers": [ { "url": "https://api.nue.io/v1/stripe/metadata-mapping", "description": "Nue API Production URL" }, { "url": "https://api.sandbox.nue.io/v1/stripe/metadata-mapping", "description": "Nue Sandbox API Server" } ], "name": "Create Metadata Mappings", "description": "Register multiple metadata mappings to define how data flows from Nue objects to Stripe entities. Mappings can connect Nue Customer and Order objects to Stripe Customer and Invoice objects. Use the field discovery endpoints to find available source and target fields.", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "List of metadata mappings to create. Each mapping defines a connection between a Nue field and a Stripe field.", "customType": "CreateMetadataMappingRequest", "schema": [ { "name": "metadataMappingList", "kind": "required", "type": "array", "description": "List of metadata mappings to create", "modelRef": "#/components/schemas/MetadataMapping", "customType": "MetadataMapping[]", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "Unique identifier for the metadata mapping", "format": "uuid" }, { "name": "sourceObject", "kind": "optional", "type": "string", "description": "

The Nue object to get data from (e.g., Customer, Order)

", "example": "Customer" }, { "name": "sourceField", "kind": "optional", "type": "string", "description": "The field in the source object to get data from", "example": "billingPostalCode" }, { "name": "sourceValue", "kind": "optional", "type": "string", "description": "A static value to use instead of a field value", "example": "" }, { "name": "targetObject", "kind": "required", "type": "string", "description": "

The Stripe object to send data to (e.g., Customer, Invoice)

", "example": "Customer" }, { "name": "targetField", "kind": "required", "type": "string", "description": "The field in the target object to send data to", "example": "address.postal_code" } ] } ], "modelRef": "#/components/schemas/CreateMetadataMappingRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "apiKeyAuth", "name": "nue-api-key", "kind": "optional", "type": "apiKey", "in": "header" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "Metadata mappings created successfully. Returns the number of mappings registered in this request.", "jsonExample": "", "isExpanded": true, "subExamples": [ { "label": "GENERATED", "code": "// Metadata mappings created successfully. Returns the number of mappings registered in this request.\n0" }, { "label": "Success Response", "code": "2" } ], "schema": [ { "kind": "optional", "type": "integer", "description": "Number of mappings successfully created", "isExpanded": true } ] }, { "statusCode": "400", "description": "

Bad Request - Invalid mapping configuration

", "jsonExample": "", "isExpanded": true, "subExamples": [ { "label": "GENERATED", "code": "// Bad Request - Invalid mapping configuration\n{\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Invalid mapping configuration\",\n \"details\": [\n \"\"\n ]\n }\n}" }, { "label": "Invalid Target Field", "code": "{\n \"error\": {\n \"code\": \"INTEGRATION_MAPPING_TARGET_FIELD_NOT_PERMIT\",\n \"message\": \"Target field 'oid' is not allowed for mapping\",\n \"details\": [\n \"Stripe field 'oid' is read-only and cannot be mapped\"\n ]\n }\n}" } ], "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "error", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "code", "kind": "optional", "type": "string", "description": "Error code", "example": "VALIDATION_ERROR" }, { "name": "message", "kind": "optional", "type": "string", "description": "

Human-readable error message

", "example": "Invalid mapping configuration" }, { "name": "details", "kind": "optional", "type": "array", "description": "Additional error details", "example": "[\"Target field 'oid' is read-only\"]", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] }, { "statusCode": "401", "description": "

Unauthorized - Invalid or missing API key

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "error", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "code", "kind": "optional", "type": "string", "description": "Error code", "example": "VALIDATION_ERROR" }, { "name": "message", "kind": "optional", "type": "string", "description": "

Human-readable error message

", "example": "Invalid mapping configuration" }, { "name": "details", "kind": "optional", "type": "array", "description": "Additional error details", "example": "[\"Target field 'oid' is read-only\"]", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "ZmYnPEgf9QG_Vov0bfICg", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.nue.io/v1/stripe/metadata-mapping \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"metadataMappingList\": [\n {\n \"targetObject\": \"Customer\",\n \"targetField\": \"address.postal_code\"\n }\n ]\n }'" }, { "id": "uUskqmwEv4FBF6gv2uNY3", "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 \"metadataMappingList\": [\n {\n \"targetObject\": \"Customer\",\n \"targetField\": \"address.postal_code\"\n }\n ]\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.nue.io/v1/stripe/metadata-mapping\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "TzpsDwbZsURCwHHjGW39z", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.nue.io/v1/stripe/metadata-mapping\")\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 \"metadataMappingList\": [\n {\n \"targetObject\": \"Customer\",\n \"targetField\": \"address.postal_code\"\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "dsHLnxg2HXDs6ULKDIXYL", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.nue.io/v1/stripe/metadata-mapping\"\n\npayload = json.dumps({\n \"metadataMappingList\": [\n {\n \"targetObject\": \"Customer\",\n \"targetField\": \"address.postal_code\"\n }\n ]\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": "ZmYnPEgf9QG_Vov0bfICg" }, "results": { "languages": [ { "id": "5LHQ-06SA0xnyp3e1bJy-", "language": "200", "code": "// Metadata mappings created successfully. Returns the number of mappings registered in this request.\n0", "subExamples": [ { "label": "GENERATED", "code": "// Metadata mappings created successfully. Returns the number of mappings registered in this request.\n0" }, { "label": "Success Response", "code": "2" } ] }, { "id": "SzMkQ7GVsXYogzWGgc52i", "language": "400", "code": "// Bad Request - Invalid mapping configuration\n{\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Invalid mapping configuration\",\n \"details\": [\n \"\"\n ]\n }\n}", "subExamples": [ { "label": "GENERATED", "code": "// Bad Request - Invalid mapping configuration\n{\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Invalid mapping configuration\",\n \"details\": [\n \"\"\n ]\n }\n}" }, { "label": "Invalid Target Field", "code": "{\n \"error\": {\n \"code\": \"INTEGRATION_MAPPING_TARGET_FIELD_NOT_PERMIT\",\n \"message\": \"Target field 'oid' is not allowed for mapping\",\n \"details\": [\n \"Stripe field 'oid' is read-only and cannot be mapped\"\n ]\n }\n}" } ] }, { "id": "O4HzptymsT3EML1BA27cd", "language": "401", "code": "// Unauthorized - Invalid or missing API key\n{\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Invalid mapping configuration\",\n \"details\": [\n \"\"\n ]\n }\n}" } ], "selectedLanguageId": "5LHQ-06SA0xnyp3e1bJy-" } }, "children": [ { "text": "" } ] }