3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
13 * This api exposes CiviCRM Order objects, an abstract entity
14 * comprised of contributions and related line items.
16 * @package CiviCRM_APIv3
20 * Retrieve a set of Order.
22 * @param array $params
26 * Array of Order, if error an array with an error id and error message
27 * @throws \CiviCRM_API3_Exception
29 function civicrm_api3_order_get(array $params): array {
31 $params['api.line_item.get'] = ['qty' => ['<>' => 0]];
32 $isSequential = FALSE;
33 if (!empty($params['sequential'])) {
34 $params['sequential'] = 0;
37 $result = civicrm_api3('Contribution', 'get', $params);
38 if (!empty($result['values'])) {
39 foreach ($result['values'] as $key => $contribution) {
40 $contributions[$key] = $contribution;
41 $contributions[$key]['line_items'] = $contribution['api.line_item.get']['values'];
42 unset($contributions[$key]['api.line_item.get']);
45 $params['sequential'] = $isSequential;
46 return civicrm_api3_create_success($contributions, $params, 'Order', 'get');
50 * Adjust Metadata for Get action.
52 * The metadata is used for setting defaults, documentation & validation.
54 * @param array $params
55 * Array of parameters determined by getfields.
57 function _civicrm_api3_order_get_spec(array &$params) {
58 $params['id']['api.aliases'] = ['order_id'];
59 $params['id']['title'] = ts('Contribution / Order ID');
63 * Add or update a Order.
65 * @param array $params
71 * @throws \CiviCRM_API3_Exception
72 * @throws API_Exception
74 function civicrm_api3_order_create(array $params): array {
75 civicrm_api3_verify_one_mandatory($params, NULL, ['line_items', 'total_amount']);
76 if (empty($params['skipCleanMoney'])) {
77 // We have to do this for v3 api - sadly. For v4 it will be no more.
78 foreach (['total_amount', 'net_amount', 'fee_amount', 'non_deductible_amount'] as $field) {
79 if (isset($params[$field])) {
80 $params[$field] = CRM_Utils_Rule
::cleanMoney($params[$field]);
83 $params['skipCleanMoney'] = TRUE;
85 $params['contribution_status_id'] = 'Pending';
86 $order = new CRM_Financial_BAO_Order();
87 $order->setDefaultFinancialTypeID($params['financial_type_id'] ??
NULL);
89 if (!empty($params['line_items']) && is_array($params['line_items'])) {
90 foreach ($params['line_items'] as $index => $lineItems) {
91 if (!empty($lineItems['params'])) {
92 $order->setEntityParameters($lineItems['params'], $index);
94 foreach ($lineItems['line_item'] as $innerIndex => $lineItem) {
95 $lineIndex = $index . '+' . $innerIndex;
96 $order->setLineItem($lineItem, $lineIndex);
97 $order->addLineItemToEntityParameters($lineIndex, $index);
102 $order->setPriceSetToDefault('contribution');
103 $order->setLineItem([
104 // Historically total_amount in this case could be tax
105 // inclusive if tax is also supplied.
106 // This is inconsistent with the contribution api....
107 'line_total' => ((float) $params['total_amount'] - (float) ($params['tax_amount'] ??
0)),
108 'financial_type_id' => (int) $params['financial_type_id'],
111 // Only check the amount if line items are set because that is what we have historically
112 // done and total amount is historically only inclusive of tax_amount IF
113 // tax amount is also passed in it seems
114 if (isset($params['total_amount']) && !empty($params['line_items'])) {
115 $currency = $params['currency'] ?? CRM_Core_Config
::singleton()->defaultCurrency
;
116 if (!CRM_Utils_Money
::equals($params['total_amount'], $order->getTotalAmount(), $currency)) {
117 throw new CRM_Contribute_Exception_CheckLineItemsException();
120 $params['total_amount'] = $order->getTotalAmount();
122 foreach ($order->getEntitiesToCreate() as $entityParams) {
123 if ($entityParams['entity'] === 'participant') {
124 if (isset($entityParams['participant_status_id'])
125 && (!CRM_Event_BAO_ParticipantStatusType
::getIsValidStatusForClass($entityParams['participant_status_id'], 'Pending'))) {
126 throw new CiviCRM_API3_Exception('Creating a participant via the Order API with a non "pending" status is not supported');
128 $entityParams['participant_status_id'] = $entityParams['participant_status_id'] ??
'Pending from incomplete transaction';
129 $entityParams['status_id'] = $entityParams['participant_status_id'];
130 $entityParams['skipLineItem'] = TRUE;
131 $entityResult = civicrm_api3('Participant', 'create', $entityParams);
132 // @todo - once membership is cleaned up & financial validation tests are extended
133 // we can look at removing this - some weird handling in removeFinancialAccounts
134 $params['contribution_mode'] = 'participant';
135 $params['participant_id'] = $entityResult['id'];
136 foreach ($entityParams['line_references'] as $lineIndex) {
137 $order->setLineItemValue('entity_id', $entityResult['id'], $lineIndex);
141 if ($entityParams['entity'] === 'membership') {
142 if (empty($entityParams['id'])) {
143 $entityParams['status_id'] = 'Pending';
145 if (!empty($params['contribution_recur_id'])) {
146 $entityParams['contribution_recur_id'] = $params['contribution_recur_id'];
148 $entityParams['skipLineItem'] = TRUE;
149 $entityResult = civicrm_api3('Membership', 'create', $entityParams);
150 foreach ($entityParams['line_references'] as $lineIndex) {
151 $order->setLineItemValue('entity_id', $entityResult['id'], $lineIndex);
156 $params['line_item'][$order->getPriceSetID()] = $order->getLineItems();
158 $contributionParams = $params;
159 // If this is nested we need to set sequential to 0 as sequential handling is done
160 // in create_success & id will be miscalculated...
161 $contributionParams['sequential'] = 0;
162 foreach ($contributionParams as $key => $value) {
163 // Unset chained keys so the code does not attempt to do this chaining twice.
164 // e.g if calling 'api.Payment.create' We want to finish creating the order first.
165 // it would probably be better to have a full whitelist of contributionParams
166 if (substr($key, 0, 3) === 'api') {
167 unset($contributionParams[$key]);
171 $contribution = civicrm_api3('Contribution', 'create', $contributionParams);
172 $contribution['values'][$contribution['id']]['line_item'] = array_values($order->getLineItems());
174 return civicrm_api3_create_success($contribution['values'] ??
[], $params, 'Order', 'create');
180 * @param array $params
184 * @throws API_Exception
185 * @throws CiviCRM_API3_Exception
187 function civicrm_api3_order_delete(array $params): array {
188 $contribution = civicrm_api3('Contribution', 'get', [
189 'return' => ['is_test'],
190 'id' => $params['id'],
192 if ($contribution['id'] && $contribution['values'][$contribution['id']]['is_test'] == TRUE) {
193 $result = civicrm_api3('Contribution', 'delete', $params);
196 throw new API_Exception('Only test orders can be deleted.');
198 return civicrm_api3_create_success($result['values'], $params, 'Order', 'delete');
204 * @param array $params
208 * @throws \CiviCRM_API3_Exception
210 function civicrm_api3_order_cancel(array $params) {
211 $contributionStatuses = CRM_Contribute_PseudoConstant
::contributionStatus(NULL, 'name');
212 $params['contribution_status_id'] = array_search('Cancelled', $contributionStatuses);
213 $result = civicrm_api3('Contribution', 'create', $params);
214 return civicrm_api3_create_success($result['values'], $params, 'Order', 'cancel');
218 * Adjust Metadata for Cancel action.
220 * The metadata is used for setting defaults, documentation & validation.
222 * @param array $params
223 * Array of parameters determined by getfields.
225 function _civicrm_api3_order_cancel_spec(array &$params) {
226 $params['contribution_id'] = [
228 'title' => 'Contribution ID',
229 'type' => CRM_Utils_Type
::T_INT
,
234 * Adjust Metadata for Create action.
236 * The metadata is used for setting defaults, documentation & validation.
238 * @param array $params
239 * Array of parameters determined by getfields.
241 function _civicrm_api3_order_create_spec(array &$params) {
242 $params['contact_id'] = [
243 'name' => 'contact_id',
244 'title' => 'Contact ID',
245 'type' => CRM_Utils_Type
::T_INT
,
246 'api.required' => TRUE,
248 $params['total_amount'] = [
249 'name' => 'total_amount',
250 'title' => 'Total Amount',
252 $params['skipCleanMoney'] = [
253 'api.default' => TRUE,
254 'title' => 'Do not attempt to convert money values',
255 'type' => CRM_Utils_Type
::T_BOOLEAN
,
257 $params['financial_type_id'] = [
258 'name' => 'financial_type_id',
259 'title' => 'Financial Type',
260 'type' => CRM_Utils_Type
::T_INT
,
261 'api.required' => TRUE,
262 'table_name' => 'civicrm_contribution',
263 'entity' => 'Contribution',
264 'bao' => 'CRM_Contribute_BAO_Contribution',
265 'pseudoconstant' => [
266 'table' => 'civicrm_financial_type',
268 'labelColumn' => 'name',
274 * Adjust Metadata for Delete action.
276 * The metadata is used for setting defaults, documentation & validation.
278 * @param array $params
279 * Array of parameters determined by getfields.
281 function _civicrm_api3_order_delete_spec(array &$params) {
282 $params['contribution_id'] = [
283 'api.required' => TRUE,
284 'title' => 'Contribution ID',
285 'type' => CRM_Utils_Type
::T_INT
,
287 $params['id']['api.aliases'] = ['contribution_id'];