POST Register Transaction

Register A Transaction

This API endpoint should be called when an order is created, typically on a “Thank you” page confirming the user’s order. This API creates the transaction record within Beam’s system, and is how Beam will know to calculate donation amounts. This method should be used to create new transactions in the Beam system where the Beam widgets may not have been displayed, such as when subsequent orders in a subscription are fulfilled or charged.

Authorization

The register a transaction endpoint takes the same SDK API key that is used in your web widgets.

Authorization: "Api-Key {{SDK API key received from Beam}}"

// This will look something similar to:
Authorization: "Api-Key abc123.xyz456"

Endpoint

POST https://api.beamimpact.com/api/v3/transaction

Body

The transaction post method either takes the hashed user ID already registered from the front end (as the parameter “beamUserId”) or a user’s email (shown in the example below). Beam generates the user ID when the front end registers the user’s email with Beam. You can either always use the generated user ID or use the user’s email. Transactions are also associated directly with the order number the partner generates.

{
  "orderId": "{{ orderId }}", // String, required
  "storeId": {{ storeId }}, // Int, required
  "cartTotal": {{ cartTotal }}, // Decimal, optional
  "currencyCode": "{{ userCountryCode }}", // String, optional, 3 character ISO currenty code
  "nonprofitId": {{ nonprofitId }}, // Int, optional
  "email": "{{ userEmail }}", // String, optional
  "postalCode": "{{ userPostalCode }}", // String
  "countryCode": "{{ userCountryCode }}", // String, optional, 2 character ISO code
  "creationMethod": "recurring", // String, optional, either omit this parameter, or set to "recurring" if the order was placed as part of a recurring subscription
  "cart": { // The "cart" object is optional in the API, though is required for supporting SKU-based campaigns
    "schema": {
      "source": "generic"
    },
    "content": {
      "subscriptions": [
        {
          "remoteSubscriptionId": "{{ subscriptionId }}", // String
          "isNew": {{ true | false }} // Boolean, optional, true = This is the first order in a subscription; false = This is not the first order in a subscription
        }
      ],
      "items": [ // A list of line items in the cart
        {
          "localAmount": {{ itemAmount }}, // Decimal, required
          "remoteProductIdentifier": "{{ remoteProductIdentifier }}", // String, required
          "remoteSubscriptionId": "{{ subscriptionId }}" // String, optional
        },
        {
          "localAmount": {{ itemAmount_2 }}, // Decimal, required
          "remoteProductIdentifier": "{{ remoteProductIdentifier_2 }}", // String, required
          "remoteSubscriptionId": "{{ subscriptionId_2 }}" // String, optional
        },
      ]
    }
  },
}

Response

Beam returns a unique transaction ID for each successfully registered transaction. This ID is used to cancel transactions if necessary.

{
  transactionId: {{ transactionId }}, // Int
  userId: "{{ beamUserId }}", // String
  nonprofitId: {{ nonprofitId }} // Int
	"chainId": {{ chainId }} // Int
}

---