Overview

This integration syncs Stripe credit notes into NetSuite through PayPack. For each credit note, PayPack creates a NetSuite Credit Memo from the related invoice and, when the credit note includes refunds, a Customer Refund with the Credit Memo applied to it.

All import modes use the same PayPack configuration and field mappings, so results are consistent however a credit note is imported. Every run is logged for troubleshooting

Import Modes

Before You Start

Credit notes are matched to NetSuite through the original invoice. PayPack looks up the NetSuite invoice whose Stripe Invoice Id (PayPack) field matches the invoice on the credit note.

• The original invoice must already be imported into NetSuite (see the Stripe to NetSuite Invoice Import article).
• If no matching invoice is found, the credit note is ignored and noted in the PayPack Flow Record Log.

Configuration Settings

All credit notes settings can be found under the Refunds subtab in the Data Orchestration tab. The fields are grouped together under Credit Notes for easy access.

Note: Click any field label to see a description of its purpose and usage.

Field Descriptions

• Enable Credit Notes Flow: Check/mark to enable importing Stripe credit notes into NetSuite. Uncheck to stop all credit note imports.

• Update Stripe Credit Note Metadata: Check/mark to automatically write the NetSuite Credit Memo Internal ID back to the corresponding Stripe Credit Note after it is created

• Last Exported Date: Shows the last time credit notes were imported from Stripe (in Unix timestamp). This value is used in the next import to fetch only credit notes created after this time using the created[gte] parameter.

Note: This field is updated by the system after every flow execution and is read-only.

• Credit Memo Discount Item: Maps the NetSuite Item that represents any discounts from Stripe Credit Notes.

   Note: Use only non-inventory items. All Stripe discounts appear as a single line on the NetSuite Credit Memo.

• Credit Memo Tax Item: Maps the NetSuite item that captures taxes from Stripe credit notes.

  Note: Use only non-inventory items. All Stripe taxes are combined into a single line on the NetSuite credit memo.

Item Mapping Hierarchy

1. Configured Items (Discount, Tax): 

• If the “Credit Memo Discount Item” and/or “Credit Memo Tax Item” are configured, they are imported as single-line items on the credit note as described above.

2. Multiple Line Items:

• “Credit Memo Field Mappings” lets you link each Stripe Credit Note line to a NetSuite item.

• You can use either static or dynamic lookups to select NetSuite Items for each Stripe Credit Note line.

• Sublist mappings are required even when default items are set  (using Discount Item, or Tax Item field). Sublist mappings allow mapping beyond Item, Quantity, and Amount, ensuring all credit note lines, discounts, and taxes from Stripe are imported correctly into NetSuite

Note: 
1. Always map Item, Quantity, and Amount for tax and discount lines, plus other required fields. Quantity defaults to 1, and Amount comes from Stripe (total discounts or taxes).

2. Use the record mapping fields to map all required line-level fields.

3. For conditional mapping, always leave the default item fields blank and use static or dynamic mapping. Any values entered in these fields will override the conditional logic in the Credit Memo Field Mappings.

Refer to the Field Mapping Documentation for examples and detailed instructions on implementing conditional mappings.

• Credit memo Line Item for Applied Balance: Maps the NetSuite item that represents any Applied Balance from Stripe credit notes.

Notes: Use only non-inventory items. The applied balance appears as a line item on the NetSuite Credit Memo. To use condition-based mapping, leave this field empty and use static or dynamic mapping. Filling it in sets a global default that overrides the item, quantity and amount entries in the appliedBalance sublist of the Credit Memo Field Mappings

• Credit Memo Field Mappings: Controls how Stripe Credit Note fields are mapped to NetSuite Credit Memo fields Map the Stripe Credit Note ID (PayPack) field on the Credit Memo. PayPack uses it to recognize credit notes it has already imported.

 Note: Only fields from the Stripe Credit Note object can be used.
Refer to the Sample Credit Memo Mappings for detailed mapping configurations. Also, for detailed JSON mapping examples and instructions, refer to the Field Mapping Documentation.

• Customer Refund Account: Select the NetSuite account where Stripe refunds will be recorded. All imported customer refunds are posted to this account.

Note: To use condition-based mapping, leave the Customer Refund Account field empty and use static or dynamic mapping. Filling in this field sets a global default that overrides any conditional logic in the Customer Refund Field Mappings. 

• Customer Refund Method: Select the payment method in NetSuite for recording Stripe refunds.

Note: To use condition-based mapping, leave the Customer Refund Method field empty and use static or dynamic mapping. Filling in this field sets a global default that overrides any conditional logic in the Customer Refund Field Mappings.

• Customer Refund Field Mappings: Controls how Stripe refund fields are mapped to NetSuite customer refund fields

Note: Notes: Fields from the Stripe refund object can be used. Refund data is organized as an array within each refund object, and the related credit note and customer data are available through parent objects (for example, parent.stripeCreditnotesData.id, parent.stripeCustomerData.id). The NetSuite Credit Memo record ID is available as parent.stripeCreditnotesData.nsCreditmemoId. See the Sample Customer Refund Field Mappings below.
Refer to the Sample Credit Refund Mappings for detailed mapping configurations

For detailed JSON mapping examples and instructions, refer to the Field Mapping Documentation.

How the Import Works

Batch and On-Demand imports follow the same steps.

1. Get credit notes

• Credit notes are fetched from the Stripe API.
  • Batch: only credit notes created on or after the Last Exported Date.
  • On-Demand: only the Stripe credit note IDs you specify on the deployment.
• Credit notes already in NetSuite are skipped, using the Stripe Credit Note ID (PayPack) field on the Credit Memo.

2. Identify the related invoice

• PayPack looks up the NetSuite invoice using the Stripe invoice ID on the credit note, matched against the Stripe Invoice Id (PayPack) field (custbody_pp_stripe_invoice_id) on the invoice.
• If no invoice is found, the credit note is ignored.

3. Get the related invoice line items

• Stripe credit notes do not include product or item details by default. PayPack retrieves the lines of the Stripe invoice and compares them with the credit note's lines, then uses the items that match.

4. Get customer balance data

• If the credit note includes a customer balance ID, PayPack retrieves the balance details through the Stripe Customer Balance API.
• If not, this step is skipped.

5. Get refund data

• If the credit note includes refunds, PayPack fetches each refund from Stripe individually.
• If not, this step is skipped.

6. Create the Credit Memo

• The NetSuite invoice is transformed into a Credit Memo and your field mappings are applied, including lines, discounts and taxes.
• If mapped, the Stripe Credit Note ID is stored in the Stripe Credit Note ID (PayPack) field on the Credit Memo.
• How the Credit Memo is applied depends on the credit note:

• Applied balance is added as a separate line with a negative amount, using the appliedBalance sublist in the Credit Memo Field Mappings. If Credit memo Line Item for Applied Balance is configured, it overrides the item, quantity and amount in that sublist.
• Item-level mappings: if you need required or custom line-level fields, populate them through the item-level mappings in the Credit Memo Field Mappings. If required values are not mapped, Credit Memo creation can fail.

Note: To get the right application behavior, configure the apply sublist in the Credit Memo Field Mappings. See the sample below.

7. Create the Customer Refund

• A NetSuite Customer Refund is created after the Credit Memo when the credit note contains refunds.
• The Credit Memo is applied to the Customer Refund through the apply sublist in the Customer Refund Field Mappings.
• Both the Stripe refund and the credit note data are available for mapping (for example, parent.stripeCreditnotesData.id).
• Fields such as customer, amount and Stripe Refund ID (PayPack) are filled from your mappings.

8. Update Stripe metadata

• The NetSuite Credit Memo or Customer Refund record ID is written back to the Stripe credit note.
• Skipped if Update Stripe Credit Note Metadata is not checked.

Script Details

Batch (Map/Reduce)

Script: PayPack S2NS Creditnotes Import MR Batch. Runs on a schedule you define.

• First run: fetches credit notes created on or after the Credit note Start Date. Later runs fetch only credit notes created after the Last Exported Date, so nothing is imported twice.
• Parameters:
  • Stripe Account Id (custscript_pp_cn_stripe_acc_id): internal ID of the PayPack Stripe Account Configuration record.
  • Credit note Start Date (custscript_pp_cn_start_date): used only on the first run, or when no Last Exported Date exists. Enter a Unix timestamp in seconds, for example 1761147332. The Last Exported Date is updated automatically when a run completes.

On-Demand (Map/Reduce)

Script: PayPack S2NS Creditnotes Import MR OnDemand. Runs only when you trigger it. Use it mainly to import missing credit notes.

• Parameters:
  • Stripe Account Id (custscript_pp_od_cn_stripe_acc_id): internal ID of the PayPack Stripe Account Configuration record.
  • Stripe Credit note IDs (custscript_pp_od_stripe_cn_ids): comma-separated list of the Stripe credit notes to import.

Deploying and Scheduling

1. Go to Customization > Scripting > Scripts.
2. Filter by Type: Map/Reduce and open the Batch or On-Demand script.
3. Click Deploy Script.
4. On the deployment, set the Stripe Account Id parameter to the internal ID of the relevant PayPack Stripe Account Configuration record.
5. Batch: on the Schedule subtab, choose the event type (single, daily, weekly, monthly or yearly), start and end dates (or No End Date), and the repeat interval. Click Save.
6. On-Demand: enter the credit note IDs and use Save and Execute.

Sample Field Mappings

IDs below are placeholders. Replace them with your own values.

Credit Memo Field Mapping

{
  "fields": [
    { "generate": "location", "hardCodedValue": "<LOCATION_ID>" },
    { "generate": "custbody_pp_s2ns_credit_note_id", "extract": "id" }
  ],
  "sublist": {
    "item": [
      {
        "generate": "item",
        "dynamicLookup": {
          "recordType": "inventoryitem",
          "filters": [
            ["stockdescription", "is", "{{lines.data[].product}}"],
            "and",
            ["isinactive", "is", "F"]
          ],
          "resultField": "internalid",
          "default": "<DEFAULT_ITEM_ID>"
        }
      },
      { "generate": "quantity", "extract": "lines.data[].quantity" },
      { "generate": "price", "hardCodedValue": "-1" },
      { "generate": "amount", "handlebars": "{{toFixed (divide lines.data[].amount 100) 2}}" },
      { "generate": "taxcode", "hardCodedValue": "<TAX_CODE_ID>" }
    ],
    "discount": [
      { "generate": "item", "hardCodedValue": "<DISCOUNT_ITEM_ID>" },
      { "generate": "quantity", "hardCodedValue": 1 },
      { "generate": "price", "hardCodedValue": "-1" },
      { "generate": "amount", "hardCodedValue": 1 },
      { "generate": "taxcode", "hardCodedValue": "<TAX_CODE_ID>" }
    ],
    "tax": [
      { "generate": "item", "hardCodedValue": "<TAX_ITEM_ID>" },
      { "generate": "quantity", "hardCodedValue": 1 },
      { "generate": "price", "hardCodedValue": "-1" },
      { "generate": "amount", "hardCodedValue": 1 },
      { "generate": "ignoreInclusiveTax", "hardCodedValue": "true" }
    ],
    "appliedBalance": [
      { "generate": "item", "hardCodedValue": "<APPLIED_BALANCE_ITEM_ID>" },
      { "generate": "quantity", "hardCodedValue": 1 },
      { "generate": "price", "hardCodedValue": "-1" },
      { "generate": "amount", "hardCodedValue": "1" },
      { "generate": "location", "hardCodedValue": "<LOCATION_ID>" },
      { "generate": "taxcode", "hardCodedValue": "<TAX_CODE_ID>" },
      { "generate": "description", "extract": "StripeCustomerBalanceData.id" }
    ],
    "apply": [
      { "generate": "apply", "hardCodedValue": true },
      { "generate": "doc", "extract": "nsInvoiceRecordId" }
    ]
  }
}

Customer Refund Field Mapping

{
  "fields": [
    {
      "generate": "customer",
      "dynamicLookup": {
        "recordType": "customer",
        "filters": [
          ["custentity_nm_stripecharge_customer_id", "is", "{{parent.stripeCreditnotesData.customer}}"]
        ],
        "resultField": "internalid",
        "default": ""
      }
    },
    { "generate": "custbody_nm_pp_stripe_refund_id", "extract": "id" },
    { "generate": "paymentmethod", "hardCodedValue": "<PAYMENT_METHOD_ID>" },
    { "generate": "account", "hardCodedValue": "<ACCOUNT_ID>" }
  ],
  "sublist": {
    "apply": [
      { "generate": "apply", "hardCodedValue": "T" },
      { "generate": "doc", "extract": "parent.stripeCreditnotesData.nsCreditmemoId" },
      { "generate": "amount", "handlebars": "{{toFixed (divide amount 100) 2}}" }
    ]
  }
}