Go to SamCart.com
Welcome
Login
  1. SamCart Knowledge Base
  2. Integrations
  3. Integrating with SamCart

Notify URL

Justin Smith
Modified on: Tue, Apr 2, 2024 at 3:12 PM


Automatically send HTTP POST Notifications containing order, subscription, and customer information to your own desired endpoint.

Need to integrate SamCart with your own application or create a custom integration with your website? SamCart's Notify URL gives you the ability to do exactly that.

Below, we'll break down how to use the Notify URL in tandem with SamCart's Integration Engine to create rules allowing you to automate the management of your SamCart customers with your desired endpoint. 

Connecting Your Notify URL to the Integration Engine

Start by clicking over to your Marketplace Settings and, on the left-hand side of your screen, selecting Integrations.

Here, under the Integration Setup tab, you'll see a list of all your active integrations that are connected via the Integration Engine. To add a new Notify URL integration, click the New Integration button: 

Clicking New Integration will prompt a box to appear which will walk you through the steps required to complete the integration. Select Notify URL (1) and click Next Step (2):

SamCart will ask you to name the integration (1). This is just an internal label, and can be anything you'd like as long as it doesn't already appear in your Integrations list. 

Next, enter the Notify URL (endpoint) that would like SamCart to send an HTTP POST. Make sure you include "https://" (2). 

Lastly, click Save Changes (3):

Once the Notify URL is successfully integrated, it will appear in the Integration Setup tab.

Now we're ready to create some Integration Rules to dictate what to send to your Notify URL and when! Below, we'll go over the two types of Integration Rules in SamCart.

Creating Integration Rules at the Product Level

Now that SamCart is "connected" to your Notify URL, you'll need to establish simple rules that tell the Integration Engine to send an HTTP POST to your Notify URL when certain actions takes place in your SamCart Marketplace. 

Head over to your Product and click into the Integrations tab (1), then click New Rule (2). 

First, you’ll need to decide what action you want to perform on your integration. An action is the functionality available in an Integration you are connected to. In the Integration dropdown, select your connected Integration you'd like to set up a rule for. Then select the Integration specific Action. 

Once you have your Integration and Action selected, click on Next Step.

Next, you’ll need to select a trigger. A trigger is the event inside of your SamCart Marketplace that tells the Integration Engine it’s time to make something happen in a connected application. 

In the first dropdown on the second step, you will want to select either eCommerce or Courses. eCommerce rules will apply to actions on your product pages, while Courses triggers will be anything related to the Courses app. The available triggers in the dropdown will be specific to the selected integration. In this example, we’ll use the Product Purchased trigger as it’s the most common. 

Select Product Purchased from the drop-down menu and click Next Step:

And that's it! Click Submit and SamCart will send an HTTP POST to your Notify URL each time your Product is purchased.

NOTE: Each application has different Actions available. The following are available on Notify URL Integration

Available Integration Triggers

Product Purchased isn't the only SamCart event that can trigger an HTTP POST. Here's the full list: 

  • Product Purchased
  • Product Refunded
  • Product Added to Order
  • Subscription Canceled
  • Subscription Delinquent
  • Subscription Recovered
  • Subscription Restarted
  • Subscription Charged
  • Subscription Charge Failed
  • Order Completed
  • Upsell Purchased
  • Subscription Completed

Creating Global Integration Rules

Global Rules aren't too different from Product-Level Integration Rules, except for the fact that they're triggered by every Product in your Marketplace. For example, if you'd like to send an HTTP POST to your Notify URL whenever a customer purchases any of your SamCart Products, you'd want to create a Global Product Purchased Rule.

To create a Global Rule in SamCart, head back to your Marketplace's Integration Settings. 

Here, click on the Global Rules tab (1) and select New Rule (2):

Once you've done that, the steps to creating a Global Rule are identical to that of a Product-Level Integration Rule. Reference the "Creating Integration Rules at the Product Level:" section above for a detailed breakdown on how to proceed. 

After your Global Rule is created, it will appear under the Global Rules tab: 

Data Payload

Here's a sample JSON sent to the notification URL looks like:

{   
"type":"Order",
    "api_key":null,

    "product": {
          "id": 10,
          "name": "Test",
          "price": 25
    },

    "customer": {
          "first_name": "Brian",
          "last_name": "Moran",
          "email": "bri@samcart.com",
          "phone_number": "5551235555",
          "billing_address": "10000 Maple Lawn Blvd",
          "billing_city": "Fulton",
          "billing_state": "Maryland",
          "billing_zip": "21044",
          "billing_country": "USA"
    },

    "order": {
          "id": 12412041,
          "total": 25,
          "shipping_address": null,
          "shipping_city": null,
          "shipping_state": null,
          "shipping_zip": null,
          "shipping_country": null,
          "ip_address": "192.168.56.1",
          "stripe_id": 66,
          "subscription_id": 55,
          "custom_fields": {
               "name": "shirt size",
               "slug": "shirt-size",
               "value": "medium" 
    },

    "affiliate": {
          "id": null,
          "token": null
    }

}

Values that don’t exist (in this case, shipping address) are represented as NULL values.

Additional event payloads

Less information is passed for the following events:

  • Refund
  • Cancel
  • RecurringPaymentFailed
  • RecurringPaymentRecovered
  • RecurringPaymentSucceeded
  • Custom Field Data
{   
"type":"<eventType>",
    "api_key":"<key>",

    "product": {
          "id": 10,
          "name": "Test",
          "price": 25
    },

    "customer": {
          "first_name": "Brian",
          "last_name": “Moran",
          "email": "bri@samcart.com",
          "phone_number": "5551235555",
    },

    "order": {
          "id": 12412041,
          "total": 25,
          "ip_address": "192.168.56.1"
    }

}

Example PHP code for using this would be:

<?php 
  $inputData = json_decode(file_get_contents('php://input')); 
  $firstName = $inputData->{'customer'}->{'first_name'}; 
  $lastName = $inputData->{'customer'}->{'last_name'}; 
  $customerName = $firstName . ' ' . $lastName; echo $customerName; 
?>

Frequently Asked Questions

Q: I see Notification URL settings under the "Advanced Settings" tab of my product. Is this different from the NotifyURL integration and should I use it? 

A: The Notification URL setting that you see in the "Advanced Settings" tab of your product is actually our legacy NotifyURL integration. It functions in the same way, but is not quite as advanced as our new NotifyURL integration. You can technically use the legacy integration and it will work, however, we always recommend using our new NotifyURL integration rather than the legacy integration! The new NotifyURL integration performs better than the legacy integration, and the new one will have logs to show exactly when the integration fires and an error log if it ever does not fire or fires incorrectly. 

Please note - as this is a legacy feature, newer marketplaces might not see this in their "Advanced Settings" tab! Simply use the NotifyURL integration described in this article.

Q: My integration seems to be functioning properly, but HTTP POST isn't firing seemingly at random. What happened? 

A: If an integration rule fails to fire, there's always a reason. The Integration Engine keeps a record of the last 1,000 integration events that took place in your Marketplace, and they can be viewed by heading to Marketplace Settings > Integrations > Logs.

Here, you can search for the event in question and check if anything went wrong. 99% of the time the Logs can provide insight into exactly what might've went wrong with that action. 

Q: How can I delete, re-name, or refresh my integration if I made some changes to my Notify URL? 

A: Head to Marketplace Settings > Integrations and click the Edit, Refresh, or Delete buttons to make these changes to your integration: 

Q: Can I have multiple Notify URL's for my Marketplace/Product?

A: You can indeed!

Q: If I have a base product plus a bundled product with a "Product Purchased" trigger utilizing the Notify URL integration, will the Notify URL integration fire for both the base product AND the bundled product?

A: Yes, the "Product Purchased" trigger will fire for each item in the order. If you'd prefer for it to only fire once, you could use an "Order Completed" trigger instead.

Q: What data is sent over for each event?

A: Here are samples for each SamCart action available with Notification URL: 

Prospect Created

{
  "first_name": "SamCart",
  "last_name": "Test",
  "email": "example@samcart.com",
  "phone_number": null,
  "product_id": 350399,
  "product_name": "Product Name",
  "product_price": "10.00",
  "currency": "USD",
  "billing_addresses": [],
  "shipping_addresses": []
}

Order Completed (sends complete order) 

{
  "type": "Order",
  "api_key": null,
  "products": [
    {
      "id": 411191,
      "name": "Product Name",
      "price": "5.00",
      "status": "Charged",
      "shipping": "0.00",
      "tax": "0.00",
      "transaction_id": "ch_1Ikxxxxxxxxxxxx",
      "subscription_id": 1635935,
      "sku":"sku_1234"
    },
    {
      "id": 350399,
      "name": "Upsell Product Name",
      "price": "5.00",
      "status": "Charged",
      "shipping": "0.00",
      "tax": "0.00",
      "transaction_id": "ch_1Ikxxxxxxxxxxxx",
      "funnel_info": {
        "upsell_id": 27429,
        "funnel_id": 17455
      }
    }
  ],
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": "5552225555",
    "customer_id": 5540183,
    "billing_address": "100 Main Street",
    "billing_city": "Austin",
    "billing_state": "TX",
    "billing_zip": "78701",
    "billing_country": "United States"
  },
  "order": {
    "created_at": "2021-04-27T15:34:40-05:00",
    "id": 8674655,
    "total": "10.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_xxxxxxxxx",
    "total_tax": "0.00",
    "total_shipping": "0.00",
    "processor": "Stripe",
    "custom_fields": [],
    "upsell_custom_fields": [],
    "transaction_id": [
      "ch_1Ikxxxxxxxxxxxx",
      "ch_1Ikxxxxxxxxxxxx"
    ],
    "shipping_address": "100 Main Street",
    "shipping_city": "Austin",
    "shipping_state": "TX",
    "shipping_zip": "78701",
    "shipping_country": "United States"
  },
  "affiliate": []
}

Product Purchased  (sends each product from an order)

{
  "type": "Order",
  "api_key": null,
  "product": {
    "id": 350399,
    "name": "Product Name",
    "price": "10.00",
    "quantity": 5,
    "shipping": "0.00",
    "tax": "0.00",
    "transaction_id": "ch_1Igtzmxxxxxxxxxxx"
  },
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": null,
    "customer_id": 5584065,
    "billing_address": "100 Main Street",
    "billing_city": "Austin",
    "billing_state": "TX",
    "billing_zip": "78701",
    "billing_country": "United States"
  },
  "order": {
    "id": 8560842,
    "created_at": "2021-04-16T10:54:15-05:00",
    "total": "50.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_xxxxxxxxx",
    "total_tax": "0.00",
    "total_shipping": "0.00",
    "processor": "Stripe",
    "custom_fields": [],
    "transaction_id": [
      "ch_1Igtzmxxxxxxxxxxx"
    ],
    "shipping_address": "100 Main Street",
    "shipping_city": "Austin",
    "shipping_state": "TX",
    "shipping_zip": "78701",
    "shipping_country": "United States"
  },
  "affiliate": []
}

Product Partial Refund (refunded $10 of a $50 order)

{
  "type": "PartialRefund",
  "api_key": null,
  "product": {
    "id": 350399,
    "name": "Product Name",
    "price": "10.00",
    "transaction_id": "ch_1Igtzmxxxxxxxxxxx"
  },
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": "5552225555",
    "customer_id": 5584065
  },
  "order": {
    "id": 8560842,
    "total": "40.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_xxxxxxxxx",
    "custom_fields": [],
    "transaction_id": [
      "ch_1Igtzmxxxxxxxxxxx"
    ]
  },
  "processor": "Stripe",
  "refund_transaction_id": "re_xxxxxxxxx"
}

Product Refunded 

{
  "type": "Refund",
  "api_key": null,
  "product": {
    "id": 350399,
    "name": "Product Name",
    "price": "10.00",
    "transaction_id": "ch_1Igtzmxxxxxxxxxxx"
  },
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": "5552225555",
    "customer_id": 5584065
  },
  "order": {
    "id": 8560842,
    "total": "0.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_xxxxxxxxx",
    "custom_fields": [],
    "transaction_id": [
      "ch_1Igtzmxxxxxxxxxxx"
    ]
  },
  "processor": "Stripe",
  "refund_transaction_id": "re_xxxxxxxxx"
}

Upsell Purchased

{
  "type": "UpsellPurchased",
  "api_key": null,
  "product": {
    "id": 350399,
    "name": "Upsell Product Name",
    "price": "10.00"
  },
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": "5552225555",
    "customer_id": 5540183
  },
  "order": {
    "id": 8674655,
    "total": "10.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_xxxxxxxxx",
    "custom_fields": []
  }
}

Subscription Charged

{
  "type": "RecurringPaymentSucceeded",
  "api_key": null,
  "product": {
    "id": 440369,
    "name": "Product Name",
    "price": "10.00"
  },
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": "5552225555",
    "customer_id": 5540183
  },
  "order": {
    "id": 8675100,
    "total": "10.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_xxxxxxxxx",
    "subscription_id": 1636015,
    "custom_fields": []
  }
}

Subscription Charge Failed

{
  "type": "RecurringPaymentFailed",
  "api_key": null,
  "product": {
    "id": 440369,
    "name": "Product Name",
    "price": "10.00"
  },
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": "5552225555",
    "customer_id": 5540183
  },
  "order": {
    "id": 8675100,
    "total": "10.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_xxxxxxxxx",
    "custom_fields": [],
    "subscription_id": 1636015
  }
}

Subscription Charge Refunded

{
  "type": "SubscriptionChargeRefunded",
  "api_key": null,
  "product": {
    "id": 440369,
    "name": "Product Name",
    "price": "10.00",
    "transaction_id": "ch_1Ixxxxxxxxxxxx"
  },
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": "5552225555",
    "customer_id": 5540183
  },
  "order": {
    "id": 8675100,
    "total": "10.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_JNxxxxxxxxxxxx",
    "custom_fields": [],
    "subscription_id": 1636015,
    "transaction_id": [
      "ch_1Ixxxxxxxxxxxx",
      "ch_1Ixxxxxxxxxxxx"
    ]
  },
  "processor": "Stripe",
  "refund_transaction_id": "re_1Ixxxxxxxxxxxx"
}

Subscription Cancelled

{
  "type": "Cancel",
  "api_key": null,
  "product": {
    "id": 411191,
    "name": "Product Name",
    "price": "10.00"
  },
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": "5552225555",
    "customer_id": 5540183
  },
  "order": {
    "id": 8674655,
    "total": "10.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_xxxxxxxxx",
    "custom_fields": [],
    "subscription_id": 1635935
  }
}

Subscription Delinquent 

{
  "type": "SubscriptionDelinquent",
  "api_key": null,
  "product": {
    "id": 440369,
    "name": "Product Name",
    "price": "10.00"
  },
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": "5552225555",
    "customer_id": 5540183
  },
  "order": {
    "id": 8675100,
    "total": "10.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_xxxxxxxxx",
    "custom_fields": [],
    "subscription_id": 1636015
  }
}

Subscription Restarted & Subscription Recovered

{
  "type": "SubscriptionRestarted",
  "api_key": null,
  "product": {
    "id": 440369,
    "name": "Product Name",
    "price": "10.00"
  },
  "customer": {
    "first_name": "SamCart",
    "last_name": "Test",
    "email": "example@samcart.com",
    "phone_number": "5552225555",
    "customer_id": 5540183
  },
  "order": {
    "id": 8675100,
    "total": "10.00",
    "ip_address": "00.00.000.00",
    "stripe_id": "cus_xxxxxxxxx",
    "custom_fields": [],
    "subscription_id": 1636015
  }
}


Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.

Related Articles