Customer Management

Provisioning customers

When a new customer is provisioned in your application (for example, during registration or onboarding), you should also provision them in Stigg. You provide the customer’s unique identifier, and optionally their name, billing email address, a coupon to apply, initial subscription parameters, billing and shipping addresses (including tax IDs and payment method), and arbitrary metadata.

To control the customer’s initial access to a product according to the product’s Customer Journey settings, initial subscription parameters must be provided. To provision a customer without any default subscription, explicitly pass no subscription parameters.

Passing billing information will cause the customer to be synced to the integrated billing solution even if they don’t have any paid subscriptions. Billing information is not persisted on Stigg’s servers.

const customer = await stiggClient.provisionCustomer({
    customerId: 'customer-test-id',
    name: 'My very first customer', // optional
    email: 'john@example.com',      // optional - billing email address
    couponId: 'coupon-test-id',     // optional
    subscriptionParams: {           // optional - pass null to skip initial subscription
      planId: 'plan-basic',
      resourceId: 'resource-01',      // optional, required for multiple subscription for same product
      billableFeatures: [{ 						// optional, required for subscriptions with per unit pricing
        featureId:'feature-01-templates',
        quantity: 2
      }],
      billingPeriod: 'MONTHLY', 			// optional, relevant only for paid subscriptions
      addons: [{  										// optional
        addonId: 'addon-extra-stuff',
        quantity: 1,
      }],
      promotionCode: 'STIGG30', 			// optional
      billingCountryCode:'DK',     		// optional, required for price localization, must be in the ISO-3166-1 format
      metadata: { 									  // optional
        key: 'value',
      },
    },
    metadata: { 				// optional - metadata that will be stored in Stigg
        key: "value",
    }
});

data = await client.provision_customer(ProvisionCustomerInput(**{
  "refId": "customer-demo-123",
  "name": "Acme", 						# optional
  "email": "john@example.com", 	# optional - billing email address
  "couponRefId": "coupon-id", # optional
  "subscriptionParams": {
    "planId": "plan-revvenu-basic",
    "billingCountryCode": "DK"  # optional, required for price localization
  },
  "billingInformation": { 		# optional
    "language": "en",
    "timezone": "America/New_York",
    "billingAddress": {
      "country": "US",
      "city": "New York",
      "state": "NY",
      "addressLine1": "123 Main Street",
      "postalCode": "10164"
    },
  },
  "additionalMetaData": {			 # optional
    "key": "value"
  }
}))

result, err := client.ProvisionCustomer(context.Background(), stigg.ProvisionCustomerInput{
  CustomerID: Ptr("customer-id"),
  Name:  Ptr("Acme"), 						// optional
  Email: Ptr("john@example.com"), 	// optional - billing email address
  CouponRefID: Ptr("coupon-id"),	// optional
  SubscriptionParams: &stigg.ProvisionCustomerSubscriptionInput{ // optional
    PlanID: "plan-revvenu-basic",
    BillingCountryCode: Ptr("DK"), // optional, required for price localization
  },
  BillingInformation: &stigg.CustomerBillingInfo{ // optional
    Language: Ptr("en"),
    Timezone: Ptr("America/New_York"),
    BillingAddress: &stigg.Address{
      Country:      Ptr("US"),
      City:         Ptr("New York"),
      State:        Ptr("NY"),
      AddressLine1: Ptr("123 Main Street"),
      PostalCode:   Ptr("10164"),
    },
  },
  AdditionalMetaData: map[string]interface{}{ // optional
    "Key": "Value",
  },
})

resp = client.request(Stigg::Mutation::ProvisionCustomer, {
    "input": {
        "customerId": "CUSTOMER-ID-1",
        "name": "Acme",							# optional
        "email": "john@example.com",	# optional - billing email address
        "couponRefId": "coupon-id", # optional
      	"subscriptionParams": {
            "planId": "plan-revvenu-basic",
          	"billingCountryCode":"DK"   # optional, required for price localization
        },
        "billingInformation": {			# optional
            "language": "en",
            "timezone": "America/New_York",
            "billingAddress": {
                "country": "US",
                "city": "New York",
                "state": "NY",
                "addressLine1": "123 Main Street",
                "postalCode": "10164"
            },
        },
        "additionalMetaData": {			# optional
            "key": "value"
        }
    },
})

var resp = stigg.mutation(
  ProvisionCustomerMutation.builder()
  .input(ProvisionCustomerInput.builder()
         .customerId("customer-81726628184")
         .name("Acme")                        // optional
         .email("john@example.com")           // optional
         .billingInformation(CustomerBillingInfo.builder()
                             .billingAddress(Address.builder()
                                             .country("US")
                                             .city("New York")
                                             .state("NY")
                                             .addressLine1("123 Main Street")
                                             .postalCode("10164")
                                             .build())
                             .build())
         .additionalMetaData(new HashMap<>() {{
           put("key", "value");
         }})
         .subscriptionParams(ProvisionCustomerSubscriptionInput.builder()
                             .planId("plan-revvenu-basic")
                             .build())
         .build())
  .build()
);

var resp = await stigg.ProvisionCustomer.ExecuteAsync(new ProvisionCustomerInput()
{
  CustomerId= "customer-81726628184",
  Name = "Acme",                        // optional
  Email = "john@example.com",           // optional
  SubscriptionParams = new ProvisionCustomerSubscriptionInput()
  {
    PlanId = "plan-revvenu-basic"
  }
});

Show Result (Node.js)

{
  "customer": {
    "id": "customer-test-id",
    "experimentInfo": {
      "name": "should we use freemium?",
      "id": "should-we-use-freemium",
      "groupName": "Variant group",
      "groupType": "VARIANT"
    }
  },
  "subscriptionDecisionStrategy": "REQUESTED_PLAN",
  "subscription": {
    "id": "subscription-plan-basic-ed5dac",
    "planId": "plan-basic",
    "status": "ACTIVE",
    "addons": [],
    "customerId": "customer-test-id",
    "pricingType": "FREE",
    "resource": {
      "id": "resource-01"
    }
  }
}

Updating customers

Customer information can be updated at any time. Only the fields being updated need to be sent.

Since billing information is not persisted on Stigg’s servers, the entire billing information object must be passed each time it needs to be updated.

const customer = await stiggClient.updateCustomer({
    customerId: 'customer-test-id',
    email: 'john@example.com', // optional, use to update the customer's email address
    couponId: 'coupon-test-id',   // optional, use to apply a coupon to a customer
    billingInfo: {  							// optional, use to update the customer's billing information
        ...
    },
    metadata: {  									// optional, use to update the customer's metadata
      key: 'value',
    }
});

data = await client.update_customer(UpdateCustomerInput(
  **{
    "email": "john@example.com",
    "name": "Acme",
    "refId": "customer-id2",
    "billingInformation": {
      "payment_method_id": "pm_123123",
      "language": "en",
      "timezone": "America/New_York",
      "currency": "USD",
    },
    "additionalMetaData": {
      "key": "value"
    }
  }
))

result, err := client.UpdateCustomer(context.Background(), stigg.UpdateCustomerInput{
  CustomerID:  Ptr("customer-id"),
  Name:  Ptr("Acme"),
  Email: Ptr("john@example.com"),
  BillingInformation: &stigg.CustomerBillingInfo{
    Language: Ptr("en"),
    Timezone: Ptr("America/New_York"),
  },
  AdditionalMetaData: map[string]interface{}{
    "Key": "Value",
  },
})

resp = client.request(Stigg::Mutation::UpdateCustomer, {
    "input": {
        "customerId": "CUSTOMER-ID-1",
        "email": "john@example.com",
        "name": "Acme",
        "billingInformation": {
            "language": "en",
            "timezone": "America/New_York",
            "currency": "USD",
        },
        "additionalMetaData": {
            "key": "value"
        }
    }
})

var resp = stigg.mutation(
  UpdateCustomerMutation.builder()
  .input(UpdateCustomerInput.builder()
         .customerId("customer-demo-01")
         .name("Acme")
         .email("john@example.com")
         .additionalMetaData(new HashMap<>() {{
           put("key", "value");
         }})
         .billingInformation(CustomerBillingInfo.builder()
                             .language("en")
                             .timezone("America/New_York")
                             .currency(Currency.USD)
                             .build())
         .build())
  .build()
);

var res = await stigg.UpdateCustomer.ExecuteAsync(new UpdateCustomerInput()
{
  CustomerId = "customer-demo-01",
  Name = "Acme",
  Email = "john@example.com",
});

Show Result (Node.js)

{
  "id": "customer-test-id"
}

Getting customer data

Retrieve customer details by their customer ID, including metadata, promotional entitlements, and payment method status.

const customer = await stiggClient.getCustomer('customer-demo-01');

data = await client.get_customer_by_id(GetCustomerByRefIdInput({
  "customerId": "customer-id2"
}))

result, err := client.GetCustomerByID(context.Background(), stigg.GetCustomerByRefIDInput{
  CustomerID: "customer-f9942a",
})

resp = client.request(Stigg::Query::GetCustomerById,{
    "customerId": "customer-id"
})

var resp = stigg.query(
  GetCustomerByIdQuery.builder()
  .input(GetCustomerByRefIdInput.builder().customerId("customer-demo-01").build())
  .build()
);

var res = await stigg.GetCustomerById.ExecuteAsync(new GetCustomerByRefIdInput()
{
  CustomerId = "customer-demo-01",
});

Show Result (Node.js)

{
  "id": "customer-demo-01",
  "name": "Test Name",
  "email": "john@example.com",
  "createdAt": "2022-09-20T09:59:22.324Z",
  "updatedAt": "2022-09-20T10:00:32.750Z",
  "hasPaymentMethod": false,
  "promotionalEntitlements": [],
  "metadata": {
    "lorem": "ipsum"
  }
}

Archiving customers

When a customer is archived:

Their PII (name and email) will be nullified.
They will no longer appear in the Stigg app UI.
They will no longer be returned by the Stigg API and SDKs.

New customers cannot reuse the customer ID of archived customers. When Stigg is integrated with a billing solution, archived customers will still exist in the billing solution to allow upcoming invoices to be finalized.

Integration guides

Quick start guides

I want to...

Customer management